Users Guide

Formula One ActiveX

High performance software for manipulating data

TM TM TM TM

TM

For Microsoft Visual Basic 5.0 and 6.0 , Visual C++ 5.0 and 6.0 , and Other Languages Version 6.1

Tidestone Technologies, Inc.

Information in this document is subject to change without notice. Companies, names, and data used in examples herein are fictitious unless otherwise noted. No part of this document may be reproduced or transmitted in any form or by any means, electronic or mechanical, for any purpose, without the express written permission of Tidestone Technologies, Inc. Copyright 1999 Tidestone Technologies, Inc. All rights reserved. Formula One is a licensed trademark and Visual Components, First Impression, and VisualSpeller are registered trademarks of Tidestone Technologies, Inc. Microsoft, MS, MS-DOS, Visual Basic, and Windows are registered trademarks and Microsoft Access and Microsoft Excel are trademarks of Microsoft Corporation in the USA and other countries. Java, 100% Pure Java, and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc., in the U.S. and other countries. PowerBuilder is a trademark of Sybase, Inc. or its subsidiaries. TrueType is a registered trademark of Apple Computer, Inc. All other company and product names mentioned may be trademarks or registered trademarks of the companies with which they are associated. The Tidestone License Agreement, included with the product, specifies the permitted and prohibited uses of the product. Any unauthorized reproduction or use of the product, or breach of the terms and conditions of the License Agreement, is forbidden. The Tidestone License Agreement sets forth the only warranties applicable to the product and documentation. All warranty disclaimers and exclusions set forth therein apply to the information contained in this document. Published by: Tidestone Technologies, Inc. 12980 Metcalf Avenue, Suite 300 Overland Park, Kansas 66213 (913)851-2200 (800)884-8665 (913)851-1390 fax www.tidestone.com

Printed in the United States of America. 99/610.9

iii

Contents
Preface Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .ix New Features in Formula One . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix Version 6.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix Version 6.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . x Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . x Installing the Product . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi What Does The Installation Program Do? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi After Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xii If you Experience Installation Problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xii Technical Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xii Documentation Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii Chapter 1 Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 Adding the ActiveX Control to Your Application . . . . . . . . . . . . . . . . . . . . . . . . 1 Getting Started in Visual C++ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 Creating a Dialog, CFormView, or CView-Based Application . . . . . . . . . . . . . 2 Creating Dialog Box-Based Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 Creating CFormView-Based Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 Creating CView-Based Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 Adding the Formula One Component to Your Project . . . . . . . . . . . . . . . . . . . . 3 Adding the Component to Your Dialog or CFormView . . . . . . . . . . . . . . . . . . 4 Adding the Formula One Component to Your CView . . . . . . . . . . . . . . . . . . . . 5 Working With Top-Level Properties and Methods in Visual C++ . . . . . . . . . . . 6 Accessing Formula One Objects in Visual C++ . . . . . . . . . . . . . . . . . . . . . . . . . 6 Handling Events in your Dialog or CFormView in Visual C++ . . . . . . . . . . . . 7 Handling Events in your CView in Visual C++ . . . . . . . . . . . . . . . . . . . . . . . . . 7 Handling Printing and Previewing in Visual C++ . . . . . . . . . . . . . . . . . . . . . . . 7 Serializing the Control in Visual C++ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 Setting Properties in Visual C++ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 Setting Properties for a Control on a CView . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 Getting Started in Visual Basic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 Adding the Component to your Visual Basic 5.0 or 6.0 Project . . . . . . . . . . . . . 8 Setting Properties in Visual Basic 5.0 or 6.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 Getting Started in PowerBuilder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 OLE 2 Presentation Style . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 Uniform Data Transfer Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 Standalone Worksheet Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 Using Formula One as a Worksheet in PowerBuilder . . . . . . . . . . . . . . . . . . . 18

iv

Formula One ActiveX Users Guide

Working in PowerBuilder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 Upgrading Formula One . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

Chapter 2 Introducing Formula One . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 Working with API Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 Understanding Workbooks and Worksheets . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 Introducing the Workbook Designer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 Using Workbooks, Views, and Invisible Workbooks . . . . . . . . . . . . . . . . . . . . 25 Working With the F1Book Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 Working With the F1BookView Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 Using Attach Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 Controlling the Display of Workbook Areas . . . . . . . . . . . . . . . . . . . . . . . . . . 30 Saving View or Invisible Workbook Information . . . . . . . . . . . . . . . . . . . . . . 32 Reading and Writing Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 Using BLOB access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 Writing out a Range of Cell Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 Chapter 3 Overview of the Workbook Designer . . . . . . . . . . . . . . . . . . . . . . . Launching the Workbook Designer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Docking the Toolbars . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using the Workbook Designer Menus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using the Workbook Designer Toolbars . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 36 37 37 42

Chapter 4 Workbook Fundamentals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 Setting up Workbooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 Displaying Parts of the Workbook Designer . . . . . . . . . . . . . . . . . . . . . . . . . . 45 Setting the Default Font . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 Setting Up the Color Palette . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48 Manipulating Worksheets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48 Inserting Worksheets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49 Selecting Worksheets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 Working with a Group of Worksheets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 Inserting Multiple Worksheets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 Deleting Worksheets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54 Renaming Worksheets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55 Setting Display Options for Worksheets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55 Navigating Through Worksheets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 Navigating with the Mouse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57 Navigating with the Keyboard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58 Selecting Cells . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60 Selecting Cells with the Mouse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60 Selecting Cells with Properties and Methods . . . . . . . . . . . . . . . . . . . . . . . . . . 61 Selecting Rows and Columns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61 Setting Selection Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

Contents

Chapter 5 Working With Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63 Understanding Worksheet Data Entry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63 Adding the Formula Bar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64 Entering Data with Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64 Entering Multi-Line Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65 Understanding Worksheet Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66 Entering Constant Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66 Entering Formulas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67 Using Formula Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68 Understanding Cell References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69 Understanding Worksheet Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72 Displaying Formulas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72 Built-In Worksheet Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72 Understanding Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73 Entering Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73 Using Autofill Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74 Adding Autofill Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75 Deleting Autofill Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76 Using Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76 Calculating Worksheets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77 Setting Automatic Recalculation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77 Setting Minimal Recalculation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78 Solving Circular References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79 Limiting Data Entry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80 Denying Access to a Workbook . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80 Denying Access to a Worksheet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81 Denying Access to Certain Cells . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81 Denying Access to Row and Column Headings . . . . . . . . . . . . . . . . . . . . . . . . 82 Restricting Cell Data to Certain Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82 Denying Entry of Formulas in a Worksheet . . . . . . . . . . . . . . . . . . . . . . . . . . . 85 Restricting the Use of Certain Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85 Restricting the Use of Certain Mouse Actions . . . . . . . . . . . . . . . . . . . . . . . . . 86 Chapter 6 Editing Worksheets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87 Copying, Moving, and Pasting Selections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87 Using Dragging to Move, Copy, and Paste Selections . . . . . . . . . . . . . . . . . . . 87 Using Menu Commands to Move, Copy, and Paste Selections . . . . . . . . . . . . 91 Using Methods to Edit, Move, Copy, and Paste Selections . . . . . . . . . . . . . . . 92 Transferring Data via Uniform Data Transfer . . . . . . . . . . . . . . . . . . . . . . . . . 93 Finding and Replacing Data in Formula One . . . . . . . . . . . . . . . . . . . . . . . . . . 94 Inserting Cells, Rows, and Columns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96 Clearing and Deleting Cells, Rows, and Columns . . . . . . . . . . . . . . . . . . . . . . 97 Sorting Data in Worksheets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98

vi

Formula One ActiveX Users Guide

Chapter 7 Formatting Worksheets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99 Using Built-in Number Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99 Applying Number Formats to Rows and Columns . . . . . . . . . . . . . . . . . . . . . 101 Obtaining Formatted Text Programmatically . . . . . . . . . . . . . . . . . . . . . . . . . 101 Creating Custom Number Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102 Formatting Fonts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106 Aligning Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107 Merging Cells . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109 Cutting, Copying, and Pasting Merged Cells . . . . . . . . . . . . . . . . . . . . . . . . . 109 Changing Row Height and Column Width . . . . . . . . . . . . . . . . . . . . . . . . . . . 110 Setting Default Row Height and Width . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110 Sizing Rows and Columns Using Menu Commands . . . . . . . . . . . . . . . . . . . 111 Sizing Rows and Columns Using Click and Drag Actions . . . . . . . . . . . . . . . 112 Sizing Rows and Columns with Properties and Methods . . . . . . . . . . . . . . . . 113 Freezing Horizontal and Vertical Panes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115 Setting Cell Border and Fill Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116 Setting Cell Borders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116 Setting Cell Fill Colors and Patterns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118 Formatting Row and Column Headings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119 Selecting Row and Column Heading Areas . . . . . . . . . . . . . . . . . . . . . . . . . . 119 Sizing Row and Column Headings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120 Setting Row and Column Heading Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120 Chapter 8 Working With Graphical Objects . . . . . . . . . . . . . . . . . . . . . . . . . 123 Creating Graphical Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123 Creating Graphical Objects with Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . 123 Interactively Drawing Graphical Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124 Picture Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125 Setting Mouse Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126 Identifying Graphical Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126 Naming Graphical Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128 Selecting Graphical Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128 Interactively Selecting Graphical Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129 Selecting Graphical Objects Programmatically . . . . . . . . . . . . . . . . . . . . . . . 129 Moving, Sizing, and Arranging Graphical Objects . . . . . . . . . . . . . . . . . . . . . 130 Interactively Moving and Sizing Graphical Objects . . . . . . . . . . . . . . . . . . . . 130 Positioning Graphical Objects Programmatically . . . . . . . . . . . . . . . . . . . . . . 131 Determining Graphical Object Position and Size . . . . . . . . . . . . . . . . . . . . . . 132 Arranging Overlapping Graphical Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . 132 Formatting Graphical Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133 Formatting Colors and Patterns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133 Formatting Lines (Borders) on Graphical Objects . . . . . . . . . . . . . . . . . . . . . 134 Showing and Hiding Graphical Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135

Contents

vii

Formatting Dropdown List Boxes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135 Formatting Check Boxes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136 Formatting Buttons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137 Selecting Check Box and Dropdown List Box Items . . . . . . . . . . . . . . . . . . . 137 Setting Values Interactively . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138 Setting Values Programmatically . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138 Setting Values by Cell Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138 Editing Polygons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139

Chapter 9 Working With Chart Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141 Creating Charts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141 Using the Chart Wizard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142 Navigating in the Chart Wizard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142 Using the Gallery Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143 Using the Style Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143 Using the Layout Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144 Using the Axes Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144 Chart Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146 Referencing Data on Another Worksheet . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147 Chapter 10 Printing Worksheets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Printing Worksheets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Specifying Print Areas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Specifying Print Titles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Specifying Page Breaks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Specifying Margins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Setting Page Numbering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Specifying Headers and Footers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Setting Page Orientation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Setting Up Scaling for Printing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Specifying Page Printing Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Choosing Paper Size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Specifying Miscellaneous Printing Options . . . . . . . . . . . . . . . . . . . . . . . . . . Previewing Your Printout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149 149 150 151 152 154 155 156 157 157 158 158 158 159

Chapter 11 Working With Databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161 Overview of Formula One Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161 Installing the ODBC Drivers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161 Setting up a Data Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162 Connecting to the Data Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162 Querying the Data Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164 Updating or Inserting Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167 Using PREPARE Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168 Binding Worksheet Columns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169

viii

Formula One ActiveX Users Guide

Executing PREPARE Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170 Disconnecting from the Data Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170

Chapter 12 Using Formula One With the Internet . . . . . . . . . . . . . . . . . . . . 171 Writing out a Worksheet File in HTML Format . . . . . . . . . . . . . . . . . . . . . . . 171 Embedding Formula One Data in an HTML file . . . . . . . . . . . . . . . . . . . . . . 172 Introducing Internet Application Development . . . . . . . . . . . . . . . . . . . . . . . . 173 Viewing a Web Page Containing Formula One . . . . . . . . . . . . . . . . . . . . . . . 173 Adding Formula One to your Web Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174 Using Methods and Events for Internet Development . . . . . . . . . . . . . . . . . . 174 Understanding Formula Ones IObjectSafety Support . . . . . . . . . . . . . . . . . . 174 Understanding Formula Ones Safe Events . . . . . . . . . . . . . . . . . . . . . . . . . . 175 Chapter 13 Performance Tuning and Specifications . . . . . . . . . . . . . . . . . . Using Performance Tuning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Optimizing Formula One . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Understanding Formula Ones Data Structure . . . . . . . . . . . . . . . . . . . . . . . . Allocating and Freeing Memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Filling Worksheets with Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using Technical Specifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177 177 178 178 179 179 180

Chapter 14 Creating Add-In Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183 Formula One ActiveX Add-Ins in Visual Basic . . . . . . . . . . . . . . . . . . . . . . . 183 General Design Principles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183 Thread Safety . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184 Add-In Function Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184 Visual Basic Example Add-Ins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186 Formula One C++ Add-In API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189 How Add-In Functions Are Declared . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189 How Add-In Functions Are Exposed to Formula One . . . . . . . . . . . . . . . . . . 190 How Arguments and Return Values Are Passed . . . . . . . . . . . . . . . . . . . . . . 191 IF1AddInArrayEx interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194 Formula Evaluation Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198 C++ Example Add-In . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198 Chapter 15 A-Z Worksheet Function Reference . . . . . . . . . . . . . . . . . . . . . . 203 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297

Preface

ix

P R E F A C E

Overview

Formula One is a high-performance workbook control that allows you to create, manipulate, and print worksheets. It contains the tools needed to store, analyze, manipulate, and present your data.

New Features in Formula One

Version 6.0
s

Excel 97 support. Formula One supports the Excel 97 and 95 file formats. Formula One reads and writes worksheets compatible with Excel 97 and 95. Minimal recalculation. Formula One now supports minimal recalculations. Under some circumstances, this can cause a dramatic improvement in recalculation speed. For information on minimal recalculation, see Setting Minimal Recalculation on page 78. Worksheet size has quadrupled. Formula One now supports worksheets up to 65,536 rows long. This is four times the number of rows that the previous version of Formula One provided. Cell capacity has increased. Each cell in a worksheet can contain as much as 16KB of text. Cells can now be merged. Formula One lets you merge two or more adjacent cells. This opens up a wide range of worksheet formatting possibilities. For example, developers and users can use merged cells to quickly and easily create multicolumn headings and titles, to insert blocks of text in worksheets, or to specify backgrounds and borders. For more information on cell merging, see Merging Cells on page 109. New find and replace method. The Formula One API has a new and improved way of doing find and replace through the API. It uses a a new API object, F1FindReplaceInfo. A search can be set up by using the new DefineSearch method to create a FindReplaceInfo object. The search itself is done using the

Formula One ActiveX Users Guide

new FindNext method. The new Replace method replaces the found data with new data. For information about these new objects and methods, see the Formula One Online Documentation.
s

New format for fractions. Formula One now allows users to specify the denominator for fractional data. Now you can express a value of 0.8 as 4/5 or as 8/10 or even as 80/100. Enhanced printing features. Several printing improvements have been added to this version. Included is the new F1PageSetup Object that gives developers a wide range of paper size choices, increased control over worksheet page numbering, and the ability to set the number of copies Formula One prints by default. The Page Setup dialog box has also been redesigned. For more information on the new Page Setup features, see Printing Worksheets on page 149. Increased date range. Dates through the year 9999 are now accepted. The limit in previous versions of Formula One was 2078. Improved cell editing. When editing a cell, the in-cell edit space expands as needed to accommodate input. New worksheet function. Formula One now supports the SUMPRODUCT worksheet function. See page 263. Mouse handling. Support now exists for the IntelliPoint mouse. Hiding the scroll bars will prevent the user from using the mouse wheel to scroll.

Version 6.1
s

Add-In Functions. Formula One Version 6.1 provides Add-In function support using Visual Basic and C++. This allows developers to add their own functions to Formula One. See Creating Add-In Functions on page 183 for details.

Installation
The Installer Program can be used to install both trial and working versions of Formula One. You are prompted for a valid serial number during installation. If you enter a valid serial number, Formula One successfully installs as a working developer version. The product is installed as a trial (demo) version if you do one of the following:
s

press ENTER at the serial number prompt unsuccessfully attempt to enter a serial number three times

After the third attempt, the product installs as a trial version.

Preface

xi

The trial version of a product is a NON-REDISTRIBUTABLE component and will expire after 30 days. You cannot deploy applications with this version. The trial version displays the About box every 30 minutes reminding you that you are working with an evaluation version of the product. If you wish to continue evaluating the product after the 30-day trial, contact Tidestone at (913) 851-2200 or [email protected].

Installing the Product

The Setup program creates new directories and copies product files to your hard disk.

To install a Tidestone ActiveX control on your hard disk:

1. Insert the first disk in your drive. 2. Locate and double-click SETUP.EXE. 3. Follow the Setup program directions.

What Does The Installation Program Do?

The Installer performs the following tasks during the installation process:
s

Allows you to identify the components you want to install, select a directory to hold the program files, and specify a folder in which to place the program on your desktop. Copies the files to your hard disk. Updates system files in your Windows system directory or the location of your choice. Records your serial number. During the installation process, you enter the product serial number provided on the installation media and product registration card. The serial number is recorded and displayed in your products About Box. You are required to provide your serial number to receive technical support and upgrade pricing on future product releases. Registers the ActiveX control with the Windows Registration Database. This makes the control visible and available to your development environment.

xii

Formula One ActiveX Users Guide

After Installation
Once you install the product, you can determine if you have a full version of the product or a trial version by displaying the About box. To display the About box, use the AboutBox method or choose Help > About VCF1 in the standalone Workbook Designer. Text in the About Box tells you whether you are using an evaluation copy. After you successfully install a full version on your system, you can distribute that ActiveX control to your end users without worrying that the About box might display on their system every 30 minutes.

If you Experience Installation Problems

If you experience problems installing this product, please read the file INSTPROB.DOC located on the installation media. This file contains suggestions for fixing the most common installation problems. If problems persist, contact Tidestone Technical Support for further assistance.

Technical Support
The Tidestone technical support staff can help you with any problem you encounter installing or using Formula One. If you need assistance, contact Tidestone in any of the following ways:
s

On the World Wide Web. For best service, send your technical support requests directly to the Tidestone Case Tracking System, which you can access from the Tidestone web site. Point your browser at: http://www.tidestone.com/support/tsmain.htm

By telephone. You can contact our technical support staff at (913) 851-2200 on weekdays between 9:00 a.m. and 4:00 p.m., central time. By fax. You can contact us by FAX at (913) 851-1390. By mail. Address your correspondence to: Tidestone Technical Support Department 12980 Metcalf, Suite 300 Overland Park, KS 66213

Preface
s

xiii

In Europe, contact: Tidestone Europe Lenexa House 11 Eldon Way Paddock Wood, Kent England TN12 6BE Tel: +44 1892 834343 Fax: +44 1892 835843

Documentation Conventions
Throughout this documentation, typographic conventions are used to define elements and references to Formula One items. .
Convention example AxisSelected, AllowSelections, Select, Description Names of events, properties, and methods, are in proper case and bold font. A series of numbered instructions are preceded by an introductory line. The introductory line begins with an arrowhead. Numbered instructions provide step-by-step directions for performing tasks. The instructions should be performed in the order they are presented. In numbered steps, items you are to enter are shown in Letter Gothic font. In general sections, italic text is used for the first occurrence of a new term. In reference sections, italic text indicates variable or argument information you must supply. In reference sections, italic text surrounded by square brackets indicates optional arguments. In reference sections, text surrounded by braces indicates you must make a choice among the items inside the braces. Choices are separated by vertical bars. Letter Gothic font is used for all code examples. File names are presented in upper case text. comment. Format > Sheet > Properties Choose the Properties option on the Sheet submenu of the Format menu.

To install Formula One:

1.Type a:\setup.

workbook fontname

[axis_id] {TRUE|FALSE}

F1Book2.ATTACH F1Book1.Title

TTF16.OCX

VtChart1. RowCount number of rows In code examples, an apostrophe precedes a

Tidestone

Chapter 1 Getting Started

C H A P T E R

Getting Started

The Formula One control can be used as an ActiveX control with several Windows-based development environments, including Microsoft Visual Basic, Microsoft Visual C++, and PowerBuilder. This chapter describes how to get started using Formula One with these development environments.

Adding the ActiveX Control to Your Application

The process you use to add an ActiveX control to your application varies slightly from one development environment to another.

To add an ActiveX control, in most cases:

s

add the control to your project select the controls tool from the toolbar and draw the control on a form or in a window

For steps about adding the Formula One control to your application, refer to the following sections:
s

Getting Started in Visual C++ on page 1 Getting Started in Visual Basic on page 8 Getting Started in PowerBuilder on page 9

Getting Started in Visual C++

Before using Formula One with Visual C++, you should read the Microsoft Visual C++ documentation and on-line help. The following section highlights procedures required to use Formula One as an ActiveX control with the Microsoft Visual C++ 5.0 and 6.0 environments.

Formula One ActiveX Users Guide

Important Visual C++ does not read constants such as F1Auto from the ActiveX control, so the file TTF16.h, distributed with Formula One, should be included wherever such constants are used.

Creating a Dialog, CFormView, or CView-Based Application

To create a Dialog, CFormView, or CView-based ActiveX control application
in Visual C++ 5.0 or 6.0: 1. Start Visual C++. 2. Choose File > New to display the New dialog box. 3. Select the Projects tab. 4. Browse to locate the desired directory path. 5. Type a name for your project in the Name text box, This creates a sub-directory of that name in the current path. 6. From the Type list, select MFC AppWizard(exe) to create a project based on the MFC library. 7. Click OK. The MFC AppWizard - Step 1 dialog box appears.
s

To create a Dialog-based application select the Dialog radio button and click NEXT. Refer to Creating Dialog Box-Based Applications on page 2. To create a CFormView-based application select the Single Document or Multiple Documents radio button. Refer to Creating CFormView-Based Applications on page 3. To create a CView-based application select the Single Document or Multiple Documents radio button. Refer to Creating CView-Based Applications on page 3.

Creating Dialog Box-Based Applications

To create a dialog box-based application, be sure to complete the steps in Creating a Dialog, CFormView, or CView-Based Application on page 2 before continuing with the following steps:

To create a dialog-based application in Visual C++ 5.0 or 6.0:

1. Click the FINISH button to accept the default options. Visual C++ builds your project.

Chapter 1 Getting Started

The New Project Information dialog box appears. 2. Click OK.

Creating CFormView-Based Applications

To create a CFormView-based application, be sure to complete the steps in Creating a Dialog, CFormView, or CView-Based Application on page 2 before continuing with the following steps:

To create a CFormView-based application in Visual C++ 5.0 or 6.0:

1. Click NEXT until you get to the dialog box in step 6. 2. In the Step 6 dialog box, select the class view name from the class list at the top of the dialog box. CView appears in the Base Class list. 3. In the Base Class list, change CView to CFormView. 4. Click FINISH for Visual C++ to build your project.

Creating CView-Based Applications

To create a CView-based application, be sure to complete the steps in Creating a Dialog, CFormView, or CView-Based Application on page 2 before continuing with the following steps:

To create a CView-based application in Visual C++ 5.0 or 6.0:

1. Click FINISH to accept the default options. Visual C++ builds your project. The New Project Information dialog box appears. 2. Click OK.

Adding the Formula One Component to Your Project

When Visual C++ adds components to your project, it creates CPP and H source files defining the classes, properties, and methods for the control. It is a good idea to take a look at these files to understand what they contain. Methods and properties are not accessed the same in C++ as they are in many other languages like Visual Basic. When these files are generated, Visual C++ creates both a Get and Set method for most properties.

To add a Formula One component to your project in Visual C++ 5.0 or 6.0:
1. Choose Project > Add To Project > Components and Controls to display the Components and Controls Gallery dialog box. 2. Select the Registered ActiveX Controls folder.

Formula One ActiveX Users Guide

3. If the Formula One Control icon is not visible in the list, then the control was not registered properly and you may need to reinstall or try to register it from the ActiveX Control Test Container, which is available in the Tools menu of Visual C++. 4. Select the control from the Component list and click Insert. Click OK. The Confirm Classes dialog box appears. 5. Click OK to confirm and exit the dialog box. 6. Click Close to exit the Component Gallery. The Formula One Control appears in the Control palette.

Adding the Component to Your Dialog or CFormView

To add the component to your dialog or CFormView in Visual C++ 5.0 or 6.0:
1. In the Resource Editor, display the dialog box for which you want to place Formula One. 2. Click the Formula One component in the Editors Control palette. 3. Draw the component on the dialog box. 4. Size and place the component using the handles around the control. 5. Click the right mouse button to display the context menu. You can view and modify the design-time properties using the context menu.

Assigning Member Variables

After you add the workbook control to the dialog box, you must assign a member variable to the control to gain access to the methods and properties at runtime.

To assign member variables (for CForm or Dialog-based applications) in

Visual C++ 5.0 or 6.0: 1. Choose View > ClassWizard. 2. Select the Member Variables tab. 3. Select the Formula One control in the Control ID window and click the Add Variable button. The Add Member Variable dialog box displays. 4. Type the member variable name (e.g., something like m_F1) and click OK to accept the default variable category and type.

Chapter 1 Getting Started

The MFC ClassWizard dialog box displays the variable in the Control ID window. 5. Click OK in the MFC ClassWizard dialog box to return to your project.

Adding the Formula One Component to Your CView

To add the Formula One component to your CView in Visual C++ 5.0 or 6.0:
1. In the file list, display the header file for the view ( <projname>view.h ). 2. At the top of the file, include each of the Formula One control header files that were created when you added Formula One to your project. 3. In the Attributes section, as a public member, add the following to create member variables for each of the controls in your view:
CTTF1 m_F1;

4. Now through the file list, display the C++ source file for the view (<projname>view.cpp). 5. Start the ClassWizard, and make sure the view class is selected as the Class Name. 6. Select the View object in the Object Id list. 7. Select the Create message in the Messages list. The Create handler initially presents the following code:
return CWnd::Create(lpszClassName, lpszWindowName, dwStyle, rect, pParentWnd, nID, pContext);

Change this to the following:

if (CWnd::Create(lpszClassName, lpszWindowName, dwStyle, rect, pParentWnd, nID, pContext) == 0) return FALSE; if (m_F1.Create("Formula One", dwStyle, rect, this, 1000) == 0 return FALSE; return TRUE;

8. Start the ClassWizard, and select view class as the Class Name. 9. Select the View object in the Object Id list. 10. Select the WM_SIZE message in the Messages list. 11. Click the Add Function button to create the OnSize handler function for this message.

Formula One ActiveX Users Guide

12. Add the following code to the handler:

// TODO: Add your message handler code here if (m_F1) { m_F1.MoveWindow(0, 0, cx, cy); }

Working With Top-Level Properties and Methods in Visual C++

TTF1.H defines a number of properties and methods that affect the Formula One control. Methods are simply called as declared. However, each property has a Get and a Set method. For example, the Row property documented in the Formula One online help can be set with the SetRow method, and read with the GetRow method.

Accessing Formula One Objects in Visual C++

Formula One contains several objects, such as F1CellFormat, F1FileSpec, F1NumberFormat, etc. You can access each of these objects via wrapper classes provided by Visual C++. Wrapper classes are generated when you add the F1 control to the project.

To create an object using CreateDispatch, use the following code in Visual

C++ 5.0 or 6.0:
CF1BookView SS; COleException e; if (SS.CreateDispatch(CLSID_F1BookView, &e)) { // commence } else { e.ReportError(); ::AfxThrowOleException(e.m_sc); }

The guids (see italics above) are defined in TTF16.H and are:
CLSID_F1FileSpec CLSID_F1ODBCConnect CLSID_F1ODBCQuery CLSID_F1BookView

To use an API call to create an object, use the following code in Visual C++
5.0 or 6.0:
CF1CellFormat fmt(m_F1.CreateNewCellFormat());

Chapter 1 Getting Started

To call a method that wants an object argument, use the following code in
Visual C++ 5.0 or 6.0:
m_F1.SetCellFormat(fmt.m_lpDispatch);

Handling Events in your Dialog or CFormView in Visual C++

To assign message handlers in Visual C++ 5.0 or 6.0:
1. Start ClassWizard. 2. In the Class Name list, select the Dialog or CFormView class that was created. 3. In the Messages list, select the desired message to handle and click Add Function to add a handler. For this example, select Click event and click Add Function to add the handler. 4. Click Edit Code to edit the new function. 5. Add the following code in the function:
AfxMessageBox ("Click Event","You clicked on the workbook");

6. Run the program and when the document is clicked, the message You clicked on the workbook is displayed.

Handling Events in your CView in Visual C++

In the view header, declare the Formula One event handlers to be used, in the section with all the other AFX messages. In the view source file, implement the event handlers, and define the EVENTSINK_MAP for the workbook. An easy way to get boilerplate for these declarations and definitions is to create a CFormView project with the same name as the CView project and use ClassWizard to generate the event procedures. Then copy them into the CView project.

Handling Printing and Previewing in Visual C++

From ClassWizard, add an OnPrint override to the view. Use the Formula One FilePrintEx method to send the workbook to the printer. If previewing, you must use the PrintPreviewDCEx method.

Serializing the Control in Visual C++

Using the CopyRangeEx and WriteRangeEx methods, you can read a range of data from a file and write a range of data to a file. Alternatively, you can load and save the Formula One OLE control via its IPersistStorage interface.

Formula One ActiveX Users Guide

Setting Properties in Visual C++

You can easily set specific properties for the Formula One control in Visual C++ 5.0 and 6.0.

To set the properties of a control on a dialog or a CFormView in Visual C++

5.0 or 6.0: 1. Right-click the control in your project for which you want to set properties and choose Properties from the context menu. The Control Properties dialog box appears. 2. Select the appropriate tab for the property settings you want to modify. Properties are grouped together in categories, such as paragraphs, fonts, and pages. 3. Modify the property settings as needed. For more information on each property, see Property and Method Reference in the Formula One online help. 4. Once you set the properties for the active control, close the Control Properties dialog box to return to your project. 5. Repeat steps 1 through 4 for each control.

Setting Properties for a Control on a CView

Since a control on a CView is created dynamically at runtime, you must call Formula One methods to make any changes to its initial properties. Make these calls in the Create handler for the CView.

Getting Started in Visual Basic

The following sections highlight procedures required to use Formula One as an ActiveX control with Visual Basic, versions 5.0 and 6.0.

Adding the Component to your Visual Basic 5.0 or 6.0 Project

To insert the component into your project:
1. Choose Project > Components or press CTRL T from the keyboard. You may also right-click the component palette and choose Components from the context menu. The Components dialog box appears.

Chapter 1 Getting Started

2. Select the Tidestone Formula One control from the list of available controls. 3. If the Tidestone Formula One component is not visible in the component list, click BROWSE to add the component. 4. Click OK. The Visual Basic form is returned, and the Formula One component appears in the Component palette. 5. Double-click the Tidestone Formula One icon in the component palette to drop it on your form. You can easily set specific properties for the Formula One component, either programmatically or through the Formula One property pages.

Setting Properties in Visual Basic 5.0 or 6.0

To set properties for a component programmatically:
1. Select the component in your project for which you wish to set properties. 2. Press F4 to display the properties window. 3. Modify the property settings as needed.

To set properties for a component via the component properties pages:

1. Select the component. 2. Click the right mouse button and choose Properties from the context menu. The component property pages are displayed. 3. Within these property pages, you may set general features such as application and table name; determine what editing features are available to end users; and set the appearance features of the workbook. For more information on each property, refer to your Formula One online help.

Getting Started in PowerBuilder

This section highlights the basic procedures required to begin using Formula One as an ActiveX control with the PowerBuilder environment. For detailed information, consult your PowerBuilder documentation. You can also consult the Tidestone web site, which contains FAQs and examples on how Formula One works with PowerBuilder. Point your browser at www.tidestone.com/environ/default.htm and click PowerBuilder. The following sections include tutorials that describe the following methods:

10

Formula One ActiveX Users Guide

s

OLE 2 Presentation Style on page 10. This method inserts the Formula One control into the DataWindow and provides data via the DataWindow object. Uniform Data Transfer Method on page 14. This method simply places the Formula One control in the Application Window. Data is then copied to the clipboard where Formula One can access the data via the Uniform Data Transfer method. Standalone Worksheet Method on page 18. This method of using Formula One focuses on using it as a standalone spreadsheet without any database connectivity.

OLE 2 Presentation Style

This method inserts the Formula One control into the DataWindow and provides data via the DataWindow object.

Database Preparation
Prior to creating an application in PowerBuilder that accesses a database, you must ensure that you have correctly configured your environment. The following sections outline some preliminary measures to take before working with databases in PowerBuilder.

Configuring the ODBC

To configure the ODBC:
1. Click Configure ODBC. 2. Select the appropriate database driver from the list. 3. Click CREATE. The ODBC Database Driver Setup dialog box appears. 4. Depending on your selected database driver, the exact setup instructions might vary. Please refer to the PowerBuilder interface for instructions on how to locate your database file. In general, the ODBC Database Driver Setup dialog box prompts you for the following information. Data Source Name: A string that identifies this data source configuration in ODBC.INI. Description: An optional long description of a data source name. Database: An identification of the database file.

Chapter 1 Getting Started

11

5. If you must access a SELECT button or a BROWSE button to locate your database file, select the database file and click OK to return to the ODBC window. 6. Click OK to confirm the Setup dialog box information. 7. Click CLOSE.

Setting the Database Profile

To set the database profile:
1. Click DB Profile. The DB Profile Painter window appears. 2. Select the database file you indicated in Step 4 of Configuring the ODBC on page 10. 3. If the database does not appear, click NEW. 4. Enter a long description of the data source name. 5. Choose ODBC in the DBMS field. 6. Select the database file from the SQL Data Sources window that you indicated in Step 4 of Configuring the ODBC on page 10. 7. Click OK to exit the New Database window. 8. Click OK to exit the DB Profile window.

Creating an Application via a PowerBuilder Generated Application Template

To create an application via a PowerBuilder generated application template:
1. Click APPLICATION to open a new application. 2. Click the NEW button. The Select New Application Library dialog box appears. 3. Type a filename in the text box. 4. Click SAVE. The Save Application dialog box appears. 5. Type an Application name.

12

Formula One ActiveX Users Guide

6. Click OK. A message box appears prompting: Would you like PowerBuilder to generate an Application Template? 7. Click YES. 8. Click WINDOW to open a new window. The Select Window dialog box appears. 9. Select w_genapp_sheet from the list. 10. Click OK.

Adding the ActiveX Control to the PowerBuilder DataWindow

To add the ActiveX control to the PowerBuilder DataWindow:
1. Click DATAWINDOW. The Select DataWindow dialog box appears. 2. Click NEW. The New DataWindow dialog box appears. 3. Select QuickSelect as the DataSource. 4. Select OLE 2.0 as the presentation style. 5. Click OK. The QuickSelect dialog box appears. 6. Select the appropriate table for your database from the list. 7. Select one or more columns from the table, or select the ADD ALL button. 8. Click OK. The Insert Object dialog box appears. 9. Select the Insert Control tab. 10. Select the Tidestone Formula One control from the list of Control Types. If the control is not registered, you must register the control by clicking REGISTER NEW.

Chapter 1 Getting Started

13

11. Click OK. The Formula One Workbook Properties dialog box appears. 12. Click OK to dismiss the Tidestone Formula One Control Properties dialog box. The Formula One control appears in your DataWindow, and the Ole Object dialog box appears. 13. Select the Data tab. 14. Drag and drop any key Source data to Target data in the appropriate order for assignment. By dragging this information to the Target data window, you are linking the database columns to the Formula One worksheet. 15. Click OK. 16. Right-click the DataWindow and choose Properties. 17. Select the General tab and enter the name of the DataWindow object in the Name text box. 18. Click PREVIEW to preview the DataWindow object and retrieve data from the database to display in Formula One. 19. Close the DataWindow and indicate Yes to save the changes. 20. Type in a name for your DataWindow object. 21. Click OK. 22. Select File > Close to close the DataWindow. 23. The DataWindow prompts you if you want to save changes. Click Yes.

Connecting the DataWindow Object

To connect the DataWindow object:
1. Select Controls > DataWindow. 2. Drag and drop a DataWindow on the form. Resize as necessary. 3. Right-click on the DataWindow and choose Properties from the context menu. The DataWindow dialog box appears. 4. Assign a name to your DataWindow in the provided text box or use the default name. 5. Browse to select the name of the DataWindow object created in the section titled Adding the ActiveX Control to the PowerBuilder DataWindow on page 12.

14

Formula One ActiveX Users Guide

The DataWindow control is now bound to the DataWindow object and acts as an interface to the database. 6. Click OK to accept the values and exit back to the DataWindow dialog box. 7. Click OK to dismiss the DataWindow dialog box.

Creating a Transaction Object for the Application Open Event

To create a transaction object for the Application Open event:
1. Right-click the form. 2. Choose Script from the context menu. 3. From the Select Event drop-down list, select the Open Event for the form. 4. Append the following script to the Open Event script:
transaction DBTrans DBTrans = Create transaction DBTrans. DBMS = ODBC connect; dw_1.settransobject (SQLCA) dw_1.retrieve()

Note dw_1 represents the default DataWindow control name; supply the name of your DataWindow control as created in the section titled Creating the DataWindow Object on page 16. 5. Click the Close box on the Script window. 6. Save the script when prompted. 7. Run your application.

Uniform Data Transfer Method

This method inserts the Formula One control into the DataWindow and provides data via the DataWindow object.

Creating a New Application Window

To create a new application window:
1. Click APPLICATION to open a new application. 2. Click the NEW button.

Chapter 1 Getting Started

15

The Select Application Library dialog box appears. 3. Type a filename in the text box. 4. Click SAVE. The Save Application dialog box appears. 5. Type an Application name. 6. Click OK. A message box appears prompting: Would you like PowerBuilder to generate an Application Template? 7. Click NO.

Modifying the Application Open Event

To modify the application open event:
1. Click SCRIPT from the PowerBar. 2. From the default Select Event drop-down list, select the Open Event. 3. Modify the Open Event script to populate the SQL object and create a startup application window. The Open Event script should read as follows:
/* Populate sqlca from current PB.INI settings */ sqlca.DBMS = ProfileString ("pb.ini","database","dbms","") sqlca.database = ProfileString ("pb.ini","database","database","") sqlca.userid = ProfileString ("pb.ini","database", "userid","") sqlca.dbpass = ProfileString ("pb.ini","database","dbpass","") sqlca.logid = ProfileString ("pb.ini","database","logid","") sqlca.logpass = ProfileString ("pb.ini","database", "LogPassWord","") sqlca.servername = ProfileString ("pb.ini","database","servername","") sqlca.dbparm = ProfileString ("pb.ini","database","dbparm","") /* Uncomment the following for actual DB connection */ connect; if sqlca.sqlcode <> 0 then MessageBox ("Cannot Connect to Database", sqlca.sqlerrtext) return end if Open (w_fone_demo) // This should be the application window name that you wish to place the control in and wish to be the startup application window. (eg. W_test_demo) If it does not exist, you must create one.

16

Formula One ActiveX Users Guide

Placing the Control in the Application Window

To place the control in the application window:
1. Click the window to display the window painter. 2. To insert an OLE control, choose Controls > OLE. The Insert Object window appears. 3. Select the Insert Control tab. 4. From the Control Type list, choose the Tidestone Formula One Workbook control. 5. Click OK. 6. Click the form to draw the Formula One control in the window.

Creating the DataWindow Object

To create the DataWindow object:
1. Click DATAWINDOW. 2. Click NEW. 3. Select OLE 2.0 and click OK. 4. Select the appropriate table for your database from the list. 5. Select one or more columns from the table, or select ADD ALL. 6. Click OK. The Insert Object dialog box appears. 7. Select the Insert Control tab. 8. Select the Tidestone Formula One control from the list of Control Types. If the control is not registered, you must register the control by clicking REGISTER NEW. 9. Click OK. 10. The Formula One control appears in your DataWindow, and the Ole Object dialog box appears. 11. Click the Data tab, if necessary.

Chapter 1 Getting Started

17

12. Drag and drop any key Source data to Target data in the appropriate order for assignment. By dragging this information to the Target data window, you are linking the database columns to Formula One. 13. Click OK. 14. Click PREVIEW to preview the DataWindow object and retrieve data from the database to display in Formula One. 15. Close the DataWindow and indicate Yes to save the changes. 16. Type a name for your DataWindow object. 17. Click OK. 18. Select File > Close to close the DataWindow. 19. The DataWindow prompts you if you want to save changes. Click Yes.

Connecting the Control

To connect the control:
1. Select Controls > DataWindow. 2. Drag and drop a DataWindow on the form. 3. Right-click the DataWindow control and choose Properties from the context menu. The DataWindow dialog box appears. 4. Assign a name to your DataWindow in the provided text box or use the default name. 5. Click BROWSE to browse and select the name of the DataWindow object that you just created in the previous section titled Creating the DataWindow Object on page 16. 6. Click OK. The DataWindow control is now bound to the DataWindow object and acts as an interface to the database.

The Constructor Event

When the Constructor Event fires, data is copied from the DataWindow object to the clipboard where Formula One can access it via the Uniform Data Transfer method. 1. Right-click the Formula One control and choose Script. 2. From the default Event drop-down list, select the Constructor Event.

18

Formula One ActiveX Users Guide

3. Type the following code:

int li_rc string ls_data dw_1.settransobject(sqlca) li_rc = dw_1.retrieve() if li_rc > 0 then ls_data = dw_1.describe("datawindow.data") ole_1.SetData(ClipFormatText!, ls_data) ole_1.object.refresh() end if

4. Close the event window and confirm to save changes.

Standalone Worksheet Method

This method of using Formula One focuses on using it as a standalone spreadsheet without any database connectivity.

Using Formula One as a Worksheet in PowerBuilder

You may want to use Formula One as a worksheet in PowerBuilder without benefit of any database connectivity to supply data. You can either enter data in the Formula One worksheet yourself, or provide data to the worksheet through any number of copy methods. 1. Click APPLICATION to open a new application. 2. Click NEW. The Select New Application Library dialog box appears. 3. Type a filename in the text box. 4. Click OK. The Save Application dialog box appears. 5. Type an Application name. 6. Click OK. A message box appears prompting: Would you like PowerBuilder to generate an Application Template? 7. Click YES. 8. Click WINDOW to open a new window. The Select Window dialog box appears. 9. Select w_genapp_sheet from the list. 10. Click OK.

Chapter 1 Getting Started

19

Placing the Formula One Control in the Application Window

To place the Formula One control in the application window:
1. To insert an OLE control, choose Controls > OLE. The Insert Object window appears. 2. Select the Insert Control tab. 3. From the Control Type list, choose the Tidestone Formula One Workbook control. 4. Click OK. 5. Click the form to draw the Formula One control in the window. You can now use Formula One in the PowerBuilder environment.

Working in PowerBuilder
Calling ActiveX Properties and Methods in PowerBuilder
The syntax to access an ActiveX property or method is as follows:
<Ole_Object>.object.<Ole Property or Method>

Property Example:
Ole_1.object.ShowGridlines (False)

Method Example:
Ole_1.object.SetSelection (1,1,5,5)

Converting General Syntax into PowerBuilder Syntax

The Formula One online help provides detailed descriptions of the specific roles of each property and method. It explains all the parameters and their settings. The general syntax for the property or method you are using can be easily converted to PowerBuilder syntax if you follow the guidelines in this section:

To convert syntax for PowerBuilder:

1. Go to the script window where you want to call the property or method. 2. Select Design > Browse Object. 3. In the Browser, select the OLE tab. 4. In the Browser window, double-click Ole Custom Controls.

20

Formula One ActiveX Users Guide

5. Find the ActiveX (OCX) control that you want to access. Under the ActiveX control is a list of Properties and Functions with the proper PowerBuilder syntax.

Trapping Errors in PowerBuilder

The PowerBuilder ActiveX container has an event called ExternalException. This event fires anytime an OCX throws an exception. In the ExternalException event, there are arguments that you can check to find out the details of the exception. For example:
Script - externalexception for ole_1 MessageBox ("Exception", description)

This displays the description text of the exception that is thrown.

Handling Method Parameters Passed By Reference

To handle an ActiveX method with parameters that are passed by reference, you must place the keyword REF in front of the parameter. The following example shows this with the Formula One SaveFileDlg method.
string pBuf into FileType ole_1.object.SaveFileDlg ("Save File", REF pBuf, REF pFileType)

Upgrading Formula One

Developers who are upgrading from an earlier version of Formula One to Formula One 6.0 or 6.1 should be aware of the following issues.
s

Converting 4.x or 5.x workbooks to 6.x workbooks is as easy as opening and saving a file. To open the file, use the File > Read menu command in the Workbook Designer, the File > Open command in the standalone Workbook Designer, or the Read or ReadEx methods in the API. Then save the file in 6.0 format in order to complete the conversion. To convert 2.0 workbooks, open the standalone Workbook Designer and use the File > Import > Formula One 2.x command. This menu command is only available on the standalone Workbook Designer. After importing the file, save it in the Workbook Designer using the File > Save command. This will save it in 5.0 format. Then you may open that 5.0 file and save it in the 6.x format.

Note You can no longer read in a Formula One 2.x file programmatically. You must use the standalone Workbook Designer to import it, as described above.

Chapter 1 Getting Started

s

21

If you want to keep both versions of the software installed as components in your container, you will need to ensure that code that refers to objects specifies which version of the software you want to use. This is because the names of the objects are the same in both versions, so the container has no way of knowing which version you want. The following example, which uses the F1RangeRef object, specifies that the 6.0 version of the object should be used:
Dim Range As TTF160Ctl.F1RangeRef

Another way to fix this problem is to use either the 5.0 or the 6.x version of the software, but not both. For further information about upgrading from previous versions of Formula One, check the Tidestone website at www.tidestone.com.

Tidestone

Chapter 2 Introducing Formula One

23

C H A P T E R

Introducing Formula One

Formula One provides a high-performance workbook control that allows you to create, manipulate, and print workbooks. Workbooks are objects that are drawn on a form or in a window of an application. You can also create invisible workbooks, which allow you to perform calculations or other functions without showing a workbook on a form or in a window. These objects are maintained by Formula One. Formula One also provides the Workbook Designer. The Workbook Designer provides a graphical interface that allows you to design and format a workbook for your application by pointing and clicking and using menu commands. The Workbook Designer is also available as a stand-alone application which allows you to create Formula One spreadsheets.

Working with API Objects

Formula One provides a variety of API objects that are useful for the development of your applications. The main objects, F1Book and F1BookView, contain the lions share of the Formula One functionality. Of the remaining objects, only F1FindReplaceInfo actually performs actions -- the remaining objects merely hold data for the two book objects to access. The following objects are discussed in this manual and in the Formula One online help:
s

F1Book. A Formula One workbook object. An F1Book object is created when you place a Formula One workbook control on a form. F1BookView. A Formula One workbook view. An F1BookView object is a windowless, invisible workbook. It can contain data of its own, or it can be attached to a workbook, but have its own selection and view settings. F1FindReplaceInfo. A Formula One find/replace object. An F1FindReplaceInfo object contains properties and methods for find and replace operations.

24

Formula One ActiveX Users Guide

Note The following objects hold data. They must be used in conjunction with F1Book or F1BookView methods to perform actions.
s

F1CellFormat. A Formula One cell format object. An F1CellFormat object contains properties that describe a cell format. F1EventArg. A Formula One event argument object. An F1EventArg object represents a reference to a variant value. F1FileSpec. A Formula One file spec object. An F1FileSpec object contains properties that describe a workbook file. F1NumberFormat. A Formula One number format object. An F1NumberFormat object contains properties that describe a number format. F1ObjPos. A Formula One object position object. An F1ObjPos object contains properties that identify the position of a specified object. F1ODBCConnect. A Formula One ODBC connect object. An F1ODBCConnect object describes an ODBC connection. F1ODBCQuery. A Formula One ODBC query object. An F1ODBCQuery object describes a query. F1PageSetup. A Formula One page setup object. An F1PageSetup object contains properties that describe the page setup for printing worksheets. F1RangeRef. A Formula One range reference object. An F1RangeRef object contains properties that identify a range of cells. F1Rect. A Formula One rectangle object. An F1Rect object contains properties that identify the rectangular area of a range or object on a worksheet. F1ReplaceResults. A Formula One replace results object. An F1ReplaceResults object contains properties that identify how many items have been found and how many have been replaced.

Understanding Workbooks and Worksheets

When you open or create a file in Formula One, you are creating or opening a workbook. Workbooks store cell data, cell formulas, workbook formatting information, and workbook-specific information such as printing attributes and calculation attributes. You can open multiple workbooks simultaneously. Formulas in one workbook can refer to cells in other workbooks. The Formula One engine manages all open workbooks.

Chapter 2 Introducing Formula One

25

A workbook is a collection of individual worksheets.Worksheets allow you to show and analyze data. Data can be manipulated on several worksheets simultaneously, and you can base calculations on data from multiple worksheets. Worksheets are useful for organizing information into separate groups. For example, you might have the year-end sales figures for each sales region on a different worksheet within the same workbook. Having all the information in one worksheet can be cumbersome; splitting it into separate files makes working with the data inconvenient.

Introducing the Workbook Designer

The Workbook Designer, shown in the following illustration, appears and behaves much like a commercial spreadsheet application. It is useful in different ways; for example, you can use it when you are designing an application or it can be launched from your application during runtime. You can also create Formula One worksheets using the stand-alone version. Refer to Overview of the Workbook Designer in this manual for information about the specific functions of the Workbook Designer.
This toolbar provides access to common functions. Data and formulas are entered in the worksheet.

This toolbar allows you to create drawing objects.

Using Workbooks, Views, and Invisible Workbooks

In Formula One, you can create workbook controls (F1Book) and invisible workbook objects (F1BookView). This section discusses the purpose and functionality of these controls.

26

Formula One ActiveX Users Guide

Working With the F1Book Control

When you create a workbook (F1Book), a default view is automatically created. A view provides a simplified method for showing data with different options displayed. Views contain information about:
s

grid line display column and row heading display fixed row and column specifications maximum workbook viewing size

In addition, views can contain information about user permissions such as whether the user is allowed to select cells, enter or edit data, or resize rows and columns. The following illustrates the concept of one view showing data from one workbook.
Workbook

View

The view inherits the formatting and properties from the workbook.

When you update data and formulas in the workbook, they are reflected in the view, and vice versa.

A view is attached to a workbook by default; however, you can change the view to which the workbook is attached. Multiple views can be used to display specified data from one workbook, but each view can only display data from one workbook at a time. When multiple views are displaying data from the same workbook, any change made in one view is reflected in the other views. The following illustrates this concept.

Chapter 2 Introducing Formula One

The arrows indicate the portion of the workbook that is displayed in each of the views.

27

View

View Workbook

View

The view should not be confused with the F1BookView API object. A view can only accommodate data from one workbook at a time. If you want to show one workbook that includes data from multiple workbooks, use the F1BookView API object, which is discussed in the following section.

Working With the F1BookView Control

Formula One provides an F1BookView API object that allows you to create an invisible workbook control. An invisible workbook is windowless, and can only be created programmatically as an F1BookView object. The F1BookView object is useful for any situation in which you do not want to interrupt a visible workbook, form, or window. For example, it is useful when you want to perform calculations or formatting behind the scenes within the invisible workbook. In addition, if you want to build an application that shows one workbook, but includes data from multiple workbooks, you can use invisible workbooks to hold the data that you do not want the user to see. This technique works without requiring you to hide the workbooks; therefore, the users are less likely to notice changes to the visible workbook. When you want an invisible workbook to become visible, use the Attach or AttachToSS method to attach the F1BookView object to an F1Book object. When an invisible workbook is attached, the previous attachment is severed. For additional information about attaching, refer to Using Attach Methods on page 30.

28

Formula One ActiveX Users Guide

The following example shows how you can use the F1BookView API object. In this example, data shown in the F1Book control changes according to the invisible workbook that is attached to this visible workbook. The calculations and data that are displayed do not require cut or clear commands so the user is less likely to notice changes to the visible workbook.
Visible workbook.

Invisible workbook (bv1).

Invisible workbook (bv2).

When this button is clicked, this invisible workbook is shown. When this button is clicked, this invisible workbook is shown.

The following code is used to create the invisible workbooks and perform the calculations. These variables are declared:
Dim bv1 As F1BookView Dim bv2 As F1BookView

This code creates the invisible workbooks, and reads in a workbook:

Private Sub Form_Load() Dim FileName As String Set bv1 = F1Book1.CreateBookView Set bv2 = F1Book1.CreateBookView bv1.ReadEx wb1.vts bv2.ReadEx wb1.vts End Sub

This code is included for the Quarter Totals button:

Private Sub Command1_Click() F1Book1.AttachToSS bv1.SS bv1.TextRC(22, 1) = "Total"

Chapter 2 Introducing Formula One

bv1.FormulaRC(22, 2) = "sum(b2:b21)" bv1.SetSelection 22, 2, 22, 5 bv1.EditCopyRight End Sub

29

This code is included for the Region Totals button:

Private Sub Command2_Click() F1Book1.AttachToSS bv2.SS bv2.TextRC(1, 6) = "Total" bv2.FormulaRC(2, 6) = "sum(b2:e2)" bv2.SetSelection 2, 6, 21, 6 bv2.EditCopyDown End Sub

Using Properties and Methods with F1BookView

For each F1BookView API object, you can set or get properties to determine:
s

actions and tasks the user can perform the appearance of the workbook and its worksheets the content and location of cells the selection status of cells the format of data

In general, most methods and properties that perform actions such as visually formatting a workbook or calling dialog boxes are not supported by the F1BookView object because it is an invisible workbook. Specifically, you cannot use the following properties and methods with the F1BookView object:
AllowDesigner CancelEdit DefinedNameDlg DoCancelEdit DoEndEdit DoObjDblClick DoObjValueChanged DoSafeEvents DoStartRecalc FileName FilePrintSetupDlg FindEx FormatCellsDlg BorderStyle ColorPaletteDlg DefRowHeightDlg DoClick DoEndRecalc DoObjGotFocus DoRClick DoSelChange DoTopLeftChanged FilePageSetupDlg Find FormatAlignmentDlg FormatDefaultFontDlg CalculationDlg ColWidthDlg DeleteDlg DoDblClick DoObjClick DoObjLostFocus DoRDblClick DoStartEdit Enabled FilePrintPreview FindDlg FormatBorderDlg FormatFontDlg

30

Formula One ActiveX Users Guide

FormatNumberDlg FormatSheetDlg InsertDlg LineStyleDlg ObjOptionsDlg PolyEditMode ReplaceDlg SaveFileDlg ValidationRuleDlg

FormatObjectDlg GotoDlg LaunchDesigner Mode OptionsDlg ProtectionDlg ReplaceEx SaveFileDlgEx

FormatPatternDlg hWnd LaunchWorkbookDesigner ObjNameDlg PasteSpecialDlg Replace RowHeightDlg SortDlg

Using Attach Methods

You can change the view or invisible workbook that is attached to your workbook at any time using the Attach or AttachToSS method. These methods attach a view or invisible workbook to a different workbook and severs the current attachment. When using attach methods, there are several important rules to remember.
s

A view or F1BookView invisible workbook can be connected to only one workbook control at a time. An F1Book1 workbook control can have multiple views or F1BookView invisible workbooks to which it is attached. An F1Book1 workbook is always attached to a view. It ceases to exist if it is not attached to a view.

To change the view or invisible workbook in which a workbook is attached:

1. Create a workbook control. 2. Create another workbook control to act as a view. Alternatively, create an invisible workbook. 3. Attach the workbook to the view or invisible workbook using the Attach or AttachToSS method. The following code selects a workbook and attaches it to a view using the Attach method (F1Book2 is the view and F1Book1 is the workbook):
F1Book2.ATTACH F1Book1.Title

Controlling the Display of Workbook Areas

There are a number of properties you can set to determine which area of the workbook is displayed. You must identify the worksheet and range of cells to appear in the current workbook or view.

Chapter 2 Introducing Formula One

31

If the workbook contains multiple worksheets, you can specify which worksheet you want to display. This is accomplished by setting the Sheet property. Set Sheet to the index number of the worksheet you want to display. Sheets are indexed from left to right beginning with 1. Do not confuse the index with the worksheet sheet name that appears on the sheet tab. To prevent users from going to another worksheet in the workbook, you can set the ShowTabs property to F1TabsOff. This hides the sheet tabs, preventing the user from changing sheets. Alternatively, you could write code within the SelChange event to prevent the user from changing worksheets. You can limit the area of each worksheet that can be seen by setting the MinRow, MinCol, MaxRow, and MaxCol properties for each worksheet. This is particularly useful when you want to use multiple views to display different parts of the worksheet. The following illustration shows the property settings used to limit the number of rows that can be displayed in a view. The data displayed in all three views is contained in one worksheet. Notice that none of the views have vertical scroll bars. This is to prevent the end users from scrolling beyond the rows they already see.
MinCol = 1 MinRow = 2 MaxCol = 5 MaxRow = 7

MinCol = 1 MinRow = 9 MaxCol = 5 MaxRow = 14

MinCol = 1 MinRow = 16 MaxCol = 5 MaxRow = 21

32

Formula One ActiveX Users Guide

Saving View or Invisible Workbook Information

When a workbook is saved, the settings from the view or invisible workbook that requested the save operation are saved with the workbook. When a view or invisible workbook is attached to a workbook, the view settings are retrieved from the workbook.

Reading and Writing Files

Formula One can read and write a number of file formats. The following table lists the formats and the associated file name extensions.
Format Formula One Formula One 3, 4, or 5 Excel 97 Excel 5.0 or 95 Tabbed-Text Tabbed-Text (values only) HTML HTML (data only) File Extension Description .VTS .VTS .XLS .XLS .TXT .TXT .HTM .HTM Formula One 6.x format Formula One 3.x, 4.x, or 5.x format Excel 97 format Excel 5.0 or 95 format. Tab-delimited text file including number formatting information. Tab-delimited text without formatting information. HTML format including text formatting information. (Write-only format.) HTML format without graphics information. (Write-only format.)

Formula One 6.x does not support the Formula One 1.x or 2.x or Excel 4.x file formats. Since Formula One has some features not supported by Excel, files saved in the VTS file format cannot be read by Excel. The XLS format is based on records where each record represents a unique feature or property of the workbook. If the file you save contains features not supported by Excel, they are removed when the workbook is saved as an XLS file. Likewise, Excel contains features not supported by Formula One. Unsupported features are ignored when Formula One loads an Excel worksheet or workbook. Important If you load an Excel file that contains features not supported by Formula One, such as charts, drawing objects, or array formulas, those features are ignored. If the imported file is then written from Formula One as an Excel file and subsequently read by Excel, those features are omitted and irretrievable. Formula One cannot read password-protected Excel files. If you intend to read files from Excel, they should not be password-protected.

Chapter 2 Introducing Formula One

33

The following methods and properties are available for reading and writing files in Formula One applications:
Property/Method Read, ReadEx ReadFromBlob SaveFileDlg, SaveFileDlgEx Write, WriteEx WriteToBlob, WriteToBlobEx Description Reads a worksheet from disk.

Reads a worksheet that has been stored in memory in a blob variable.

This dialog box allows you to save the current file in Formula One, Excel, tabbed text format or HTML format. Saves the worksheet to a file. Writes a worksheet to a blob variable.

Using BLOB access

A Formula One workbook can also read data from or write data to a memory variable defined as a Binary Large Object (BLOB.) This allows you to store worksheets or workbooks in a database table and later retrieve them from the database table.

To retrieve a worksheet or workbook from a database table:

1. Write code outside Formula One to read a worksheet or workbook from a database table into a BLOB variable. 2. Call Formula Ones ReadFromBlob method to display that worksheet or workbook in the workbook control.

To store a worksheet or workbook in a database table:

1. Call Formula Ones WriteToBlob or WriteToBlobEx method to copy the worksheet or workbook from the Formula One control to a BLOB variable. 2. Write code outside Formula One to write the worksheet or workbook from the blob variable to a database table. Note When you use the WriteToBlob and WriteToBlobEx methods, Formula One automatically uses the latest Formula One file format. Older versions of Formula One cant read files saved in the newer versions formats. This means that developers who use more than one version of Formula One should be careful which version they use to write to BLOB memory variables.

34

Formula One ActiveX Users Guide

Writing out a Range of Cell Data

Formula One provides the following three methods for writing out a range of cell data.
s

WriteRange or WriteRangeEx. These methods write a range of cell data to a new file. InsertHTML. This method embeds a range of cell data into an existing HTML file at a specified anchor point.

To write a range of cell data to a new HTML file:

Use the WriteRange or WriteRangeEx method to identify the cell boundaries and worksheet that you want to write data from and specify the type of new file you wish to create.

To embed a range of cell data into an existing HTML file

Use the InsertHTML method to identify the cell boundaries and worksheet that you want to write data from and specify the anchor point in the file where you want the cell data embedded.

Chapter 3 Overview of the Workbook Designer

35

C H A P T E R

Overview of the Workbook Designer

The Workbook Designer is an interactive program that is available at design time, runtime, or as a standalone spreadsheet application. The Workbook Designer provides access to functions for designing and formatting a workbook by pointing and clicking and choosing commands from menus. The Workbook Designer allows you to manipulate a workbook control just like it was a part of spreadsheet application. The following illustration shows the Workbook Designer as it is displayed at design time or runtime.

Main Toolbar

Formula Bar

Drawing Toolbar

You can insert multiple worksheets.

36

Formula One ActiveX Users Guide

The following illustration shows how the Workbook Designer is displayed as a standalone spreadsheet application.

Drawing Toolbar

Main Toolbar

Formula Bar

Formatting Toolbar

Launching the Workbook Designer

The manner in which you are using the Workbook Designer determines how you launch it. You can launch the Workbook Designer using any of the following techniques:

To launch the Workbook Designer during design time:

1. Right click on the Formula One control to display the context menu. 2. Select Workbook Designer from the context menu.

To launch the Workbook Designer during runtime:

s

Double-right click on the Formula One control and the Workbook Designer is displayed.

To launch the Workbook Designer as a standalone spreadsheet application:

s

Double-click on TTF1.EXE in the Windows Explorer, or Select Start > Run and type the path to TTF1.EXE.

To launch the Workbook Designer from your application:

s

Use the LaunchDesigner method as shown in the following example:

F1Book1.LaunchDesigner

Chapter 3 Overview of the Workbook Designer

37

Calling this method displays the Workbook Designer, regardless of the setting of the AllowDesigner property. The following sections provide additional information about the Workbook Designer menus and toolbars.

Docking the Toolbars

The toolbars in the standalone Workbook Designer are dockable. This means that you can drag them to a new location within the Workbook Designer, or make them float on top of the Workbook Designer.

To move the dockable toolbars:

1. Select the toolbar you want to move. 2. Drag it to a new location.

If you drag it to an edge of the Workbook Designer, it is docked on that side of the Workbook Designer. If you drag and release the toolbar on top of the Workbook Designer, the toolbar is left floating.

Using the Workbook Designer Menus

The following tables highlight the commands available on the Workbook Designer menu bar and provide a brief description of each command.

File Menu
Command New Description Creates a new file. In the built-in version of the Workbook Designer, this action deletes any information currently in the Workbook Designer. The standalone Workbook Designer allows more than one workbook open at a time. Opens a workbook file from disk. Formula One can open files in the following formats: Formula One 3.0 or later (.VTS files), Excel 5.0 or later (.XLS files), and tabbed text (.TXT). Closes the Workbook Designer Saves the current worksheet. Formula One can save files in the following formats: Formula One 3.x, 4.x, 5.x, or 6.x (.VTS files), Excel 5.0, 95, or 97 (.XLS files), tabbed text or values-only tabbed text (.TXT), or HTML or data-only HTML (.HTM). Lets you import documents in the Formula One 2.x and Excel 4 file formats. In order for this to work, the developer or user must have a copy of Formula One 5.0 with a valid license key installed on his or her machine.

Read Open (standalone)

Close Write Save (standalone) Save As (standalone)

Import... (standalone)

38

Formula One ActiveX Users Guide

Command Page Setup Description Displays the Page Setup dialog box. This dialog box allows you to define header and footer text, page margins, page print order, page centering, worksheet-related print options, and scale. Defines the currently selected range in the active worksheet as the Print_Area user-defined name. Defines the currently selected range in the active worksheet as the Print_Titles user-defined name. Displays how the worksheet prints. Displays the standard Windows Print dialog box. This dialog box allows you to select print options, and print the active worksheet. Displays a list of the last few workbooks that Formula One has opened or created and allows the user or developer to open one or more of them. Exits the standalone Workbook Designer.

Print Area Print Titles Print Preview Print

[recent files] (standalone)

Exit (standalone)

Edit Menu
Command Cut Copy Paste Paste Special Description Cuts the current worksheet selection to the clipboard. Copies the current worksheet selection to the clipboard. Pastes the contents of the clipboard to the current worksheet selection. Pastes the formats, values, or formulas of copied cells into selected cells. In addition, Paste Special controls how data copied from a different application is pasted. Copies the current cell formatting so you can apply it to another cell. Refer to the FormatPaintMode property in the Formula One on-line help for additional information. Toggles between normal polygon editing and polygon point editing. When polygon point editing is enabled, this command is checked. Selects all of the graphical objects on the active worksheet. Displays the Sort dialog box. This dialog box allows you to set the sorting method and sort keys for data sorting. Data in the top or leftmost cell is copied down or to the right to fill the range. Clears formats and values from the selected cells. Clears only formats from the selected cells. Clears only values from the selected cells.

Copy Cell Format

Polygon Points

Select All Objects Sort Fill Clear > All Clear > Formats Clear > Contents

Chapter 3 Overview of the Workbook Designer

Command Delete Description Deletes the current selection or selected objects. Cells adjacent to the deleted cells are shifted to fill the space left by the vacated cells.

39

Delete Sheet Find

Removes the selected worksheets, and shifts the worksheets to the right of the deleted worksheets to the left. Searches in selected cells or sheets for the characters that you specify. It selects the first cell that contains those characters. Searches in selected cells or sheets for the characters that you specify, and replaces them with your specified replacement characters. Displays the Goto dialog box. This dialog box allows you to specify a cell to display in the worksheet window. The specified cell is made the active cell.

Replace

Goto

View Menu
Command Toolbar > Standard Toolbar > Drawing and Forms Formula Bar Status Bar Description Toggles the display of the Main Toolbar. Toggles the display of the Drawing Toolbar. Toggles the display of the Formula Bar. Toggles the display of the Status Bar.

Insert Menu
Command Cells Description Inserts cells at the location of the current selection. Cells adjacent to the insertion are shifted to make room for the new cells. Inserts a new row above the selected cell or row. Inserts a new column to the left of the selected cell or column. Inserts a new worksheet to the left of the selected worksheet. If more than one worksheets are selected, this command inserts the same number of worksheets that are selected. This command fails if non-contiguous sheets are selected. Inserts a First Impression chart on the active worksheet.

Rows Columns Worksheet

Chart

40

Formula One ActiveX Users Guide

Command Page Break Description Places a horizontal page break adjacent to the top edge of the active cell and a vertical page break adjacent to the left edge of the active cell. If a row or column is selected, a page break is placed adjacent to the selected row or column. Displays the Define Name dialog box. This dialog box allows you to add and delete user-defined names. Selects the Arc tool which allows you to draw arcs. Selects the Line tool which allows you to draw lines. Selects the Oval tool which allows you to draw ovals. Selects the Polygon tool which allows you to draw polygons. Selects the Rectangle tool which allows you to draw rectangles. Selects the Button tool which allows you to draw buttons. Selects the Check Box tool which allows you to draw check boxes. Selects the Drop Down List Box tool which allows you to draw drop-down list boxes. Allows you to unselect a graphical object tool.

Name Drawing Object > Arc Drawing Object > Line Drawing Object > Oval Drawing Object > Polygon Drawing Object > Rectangle Forms Object > Button Forms Object > Checkbox Forms Object > Dropdown Listbox Cancel Insert Object

Format Menu
Command Cells Description Displays the Format Cells dialog box which allows you to set cell formatting such as numeric display, alignment, fonts, borders, patterns, protection, and validation. Displays the Row Height dialog box. This dialog box allows you to set the height of the selected rows, specify default row heights, and specify automatic row height. In addition, you can specify whether the selected rows are shown or hidden Hides the selected rows, which does not delete them from the worksheet. Shows the hidden rows in a selection. Displays the Row Height dialog box which allows you to define a default height of rows. Displays the Column Width dialog box. This dialog box allows you to set the width of the selected columns, specify default column widths, and specify automatic column width. In addition, you can specify whether the selected columns are shown or hidden. Automatically adjusts the width of all cells in the column to accommodate the size of a text string or value. Hides the selected columns, which does not delete them from the worksheet.

Row > Height

Row > Hide Row > Unhide Row > Default Height Column > Width

Column > Autofit Selection Column > Hide

Chapter 3 Overview of the Workbook Designer

Command Column > UnHide Column > Default Width Sheet > Properties Sheet > Protection Description Shows the hidden columns in a selection.

41

Displays the Column Width dialog box which allows you to define a default width of columns. Displays the Format Sheet dialog box which allows you to set properties for the active worksheet. Enables protection for protected cells in the worksheet. A check next to this command means that protection is enabled. Select the command again to disable protection. Freezes the selected columns or rows. Frozen columns and rows do not scroll and cannot be edited. Unfreezes frozen panes. Displays the Default Font dialog box. This dialog box allows you to set the default font used to display data in worksheets. In addition to setting the font and font size used to display data in a worksheet, the default font affects the widths of worksheet columns. Column widths can be set in units equal to 1/256th of the character 0 (zero) in the default font. Displays the Format Object dialog box, and includes the appropriate tabbed pages for the selected object. Places the selected objects in front of other objects in the worksheet. Places the selected objects behind other objects in the worksheet.

Freeze Panes Unfreeze Panes Default Font

Object Bring to Front Send to Back

Tools Menu
Command Recalc Options Description Recalculates all open cells, worksheets, and workbooks. Accesses the Options dialog box. The Options dialog box includes tabbed pages for setting general, calculation, and color options.

A standard Window menu is provided on the standalone version of the Workbook Designer.

42

Formula One ActiveX Users Guide

Using the Workbook Designer Toolbars

The buttons on Formula Ones toolbars provide easy access to some of the most common Formula One menu items. Formula One has three toolbars: Standard, Formatting, and Drawing and Forms. You can display or hide the toolbars by toggling options in the View > Toolbars menu.

Standard Toolbar
Use the buttons on the Standard Toolbar to perform basic workbook functions such as opening, saving, and printing.
Button Name New Description Creates a new file.

Read

Opens an existing file.

Save

Saves a file.

Print

Prints the active worksheet. Displays the active worksheet in Print Preview mode. Cuts a selection to the clipboard.

Print Preview

Cut

Copy

Copies a selection to the clipboard.

Paste

Pastes from the clipboard.

Copy Format

Copies the format of the selected cells.

Toggle Drawing Toolbar

Toggles the display of the Drawing Toolbar.

Chapter 3 Overview of the Workbook Designer

43

Formatting Toolbar
Use the buttons on the Formatting Toolbar to quickly and easily format the data in the selected cell(s). This toolbar is available only with the standalone Workbook Designer. The Format Toolbar also provides drop-down lists that allow you to select fonts and font sizes.
Button Name Bold Description Controls the bold attribute for the currently selected range of data. Controls the italic attribute for the currently selected range of data. Controls the underline attribute for the currently selected range of data. Selects a color for the currently selected range of data. The color applies to the numbers and letters in the cell, not to the background or borders of the cell. Left aligns the selected range of data.

Italic

Underline

Color

Left Align

Center

Centers the selected range of data.

Right Align

Right aligns the selected range of data. Merges the selected cells and centers the selected data. This is useful for straddling heading information across rows or columns. Displays a list of common fixed and general formats. Select a format to apply it to the selected range of data. Displays a list of common currency formats. Select a format to apply it to the selected range of data.

Merge and Center

Common Fixed and General Formats

Currency

44

Formula One ActiveX Users Guide

Button Name Percent Description Displays a list of common percent formats. Select a format to apply it to the selected range of data. Displays a list of common fraction formats. Select a format to apply it to the selected range of data. Displays a list of common date and time formats. Select a format to apply it to the selected range of data.

Fraction

Date and Time

Refer to Interactively Drawing Graphical Objects on page 124 in this manual for information about the icons on the Drawing Toolbar.

Chapter 4 Workbook Fundamentals

45

C H A P T E R

Workbook Fundamentals

Before you can successfully use a Formula One control, you must understand some basic concepts about the workbook. You must understand how to select worksheets, cells, ranges, rows, and columns, enter and delete data, and display specific sections of a workbook. This chapter discusses:
s

setting up workbook defaults adding, inserting, deleting, naming, selecting, and displaying worksheets navigating through a sheet with keyboard commands and with mouse actions selecting cells and ranges selecting entire rows and columns setting selection options

Setting up Workbooks
Formula One gives you options for customizing the display and the defaults used in the Workbook Designer. In most cases, you may use the preset defaults, but you may change them if you want using the options described below.

Displaying Parts of the Workbook Designer

You may choose to change whether and how the Workbook Designer displays certain things in a workbook. These options affect all worksheets in the workbook. More display options are available per individual worksheets. To change how to display different characteristics of individual worksheets, see Setting Display Options for Worksheets on page 55.

46

Formula One ActiveX Users Guide

To change workbook display options in the Workbook Designer:

1. Choose Tools > Options and click the General tab, shown below.
You may display worksheet tabs at the top or bottom of the worksheet or turn them off. Click here to display or hide the formula bar, which appears at the top of the worksheet and shows the contents of the selected cell. Click here to display or hide the cell reference in the formula bar, which appears to the left of the formula bar and shows the cell reference of the selected cell.

Click here to display or hide type markers, which are colored frames displayed inside cells to identify the contents. Blue type markers indicate blank formatted cells, green type markers indicate values or text, and red type markers indicate formulas.

2. Choose the options you want, as described above, and click OK.

To change workbook display options programmatically:

s

Use the ShowTabs, ShowEditBar, ShowEditBarCellRef, and ShowTypeMarkers properties.

Note You can hide the worksheet tabs in order to limit users to a single worksheet in a workbook that contains multiple sheets. Use the Sheet property to make the sheet you want users to access the active sheet.

Setting the Default Font

You can set a default font, font size, and style that will apply to all worksheets in the workbook. Later you can change these settings for individual cells in the Font tab of the Format Cells dialog box. Changes you make in the Format Cells dialog box will remain, even if you change the default settings. The default font effects the widths of worksheet columns. Column widths are set in units equal to 1/256th of the character 0 (zero) in the default font, or twips, depending on the setting of the ColWidthUnits property. Because the basic unit for measuring columns can change when you change the default font, you may need to adjust the widths of columns (including the row header column) after setting the default font.

Chapter 4 Workbook Fundamentals

47

Note By default, Formula One uses Arial as the default font. Be sure you always use a TrueType font as the default font in order for print and display scaling to work correctly.

To set the default font using the Workbook Designer:

1. Select Format > Default Font. The system will display the Default Font dialog box, shown here.

A text sample with the font, style, and size you chose appears here. Some fonts provide scripts that allow you to use nonWestern alphabets. Choose the script you want here.

2. Choose the default font options you want. Click OK when you finish.

To set the default font programmatically:

s

Use the SetDefaultFont method to set basic defaults. Use the SetDefaultFontEx method to set basic defaults and specify the character set.

48

Formula One ActiveX Users Guide

Setting Up the Color Palette

Formula One comes with a predefined color palette of 56 colors. You may use those colors or you may define new colors. After you define new colors you may change them back to the preset colors.

To change colors in the color palette using the Workbook Designer:

1. Choose Tools > Options, click the Color tab, and the Color tab will appear, as shown below.

Click here to return the selected color to its default value. Click here to return all the palette colors to their default values.

2. Double-click on the color you want to change. The Windows color editor will appear, allowing you to change the settings for the selected color.

To change colors in the color palette programmatically:

s

Use the PaletteEntry property.

Manipulating Worksheets
Once you create a Formula One workbook, you should understand how to add, insert, delete, name, and select the worksheets that are contained in your workbook. For additional information about workbooks and worksheets, refer to Understanding Workbooks and Worksheets on page 24.

Chapter 4 Workbook Fundamentals

49

The following illustration shows a Formula One workbook with three worksheets:

Each of the three sheets is identified by a name displayed on a sheet tab.

Sheet Tab Space

Drag this splitter bar to shrink or enlarge the sheet tab space.

Inserting Worksheets
By default, a workbook contains only one worksheet. You can easily insert additional worksheets via the Workbook Designer or program code.

To add worksheets using the Workbook Designer:

1. Right-click on the Workbook control to display the context menu. 2. Select Workbook Designer. 3. Select Insert > Worksheet. One new worksheet is inserted to the left of the selected worksheet as shown in the following illustration:

Before adding a sheet

After adding a sheet

50

Formula One ActiveX Users Guide

Sheet Index List

Each workbook maintains an indexed list of the worksheets it contains. Worksheets are indexed from left to right beginning with 1. As you add worksheets, Formula One adjusts the index numbers so the leftmost worksheet is always index 1. Most methods and properties reference worksheets by index rather than name. It is important to remember that the sheet index is different from the name that appears on the sheet tab. Notice in the previous illustration that the worksheet is given the next available name Sheet2. However, Sheet2 is index 1 and Sheet1 is index 2.

Selecting Worksheets
Usually, you do most of your work in one worksheet at a time. This is called the active worksheet. When you have multiple worksheets in a workbook, you can use the mouse to click on a worksheets tab to make it the active sheet. The tab is highlighted and moves on top of the other tabs. You can save time and effort by performing some tasks on several sheets at once. For example, if you want all three worksheets in your workbook to have the same title information, you can select all three worksheets and enter the titles on the active worksheet. The titles are automatically entered in the corresponding cells in the other selected worksheets as well.

To select multiple worksheets in the Workbook Designer:

1. Use one of the following key/mouse combinations, depending on whether you want to select adjacent or non-adjacent worksheets:
Action CTRL-Click on sheet tab SHIFT-Click on sheet tab Result Selects or deselects non-adjacent sheets. Any other selected worksheets remain selected. Selects all adjacent worksheets between the active worksheet and the worksheet you clicked on. All other worksheets are deselected.

Chapter 4 Workbook Fundamentals

51

The following illustration shows various groupings of selected worksheets:

Sheet4 is the active sheet. All other sheets are deselected.

If you hold down the Shift key and select Sheet1, all sheets between the active sheet (Sheet4) and Sheet1 are selected.

If you select all but one sheet, and then make one of the selected sheets active by selecting it, all the other sheets remain selected.

If you hold down the Control key and select Sheet3, it is deselected, but the other sheets remain selected.

To select multiple sheets programmatically:

s

Use the SheetSelected property to toggle an individual worksheets selection status to on. The following example selects the second and third worksheets in the workbook:
SheetSelected (2) = True SheetSelected (3) = True

Working with a Group of Worksheets

When multiple worksheets are selected, you can think of them as a group of worksheets. When you perform some actions, execute some methods, or refer to some properties, they affect all the selected worksheets. Other actions affect only the active worksheet, regardless of how many worksheets are selected. In the Workbook Designer, the following actions work on all selected worksheets:
s

changing cell selection entering values via the formula bar inserting rows, columns, or ranges of cells deleting rows, columns, or ranges of cells clearing rows, columns, or ranges of cells setting TopLeft/Row/Column header text setting column width

52

Formula One ActiveX Users Guide

s

setting row height moving and copying with the mouse

Within your application code, the following methods and properties affect all selected worksheets:
Methods that affect all selected worksheets ClearRange DefColWidthDlg DeleteRange EditInsert FormatAlignmentDlg FormatFontDlg FormatSheetDlg MoveRange SetAlignment SetCellFormat SetFontEx SetProtection ValidationRuleDlg ColWidthDlg DefRowHeightDlg EditClear FilePageSetupDlg FormatBorderDlg FormatNumberDlg InsertDlg ProtectionDlg SetBorder SetColWidth SetPageSetup SetRowHeight CopyRange DeleteDlg EditDelete FilePageSetupDlgEx FormatCellsDlg FormatPatternDlg InsertRange RowHeightDlg SetBorderEx SetFont SetPattern SetValidationRule

Properties that affect all selected worksheets ColText Entry Formula FormulaLocalSRC HAlign Logical Number NumberRC ProtectionLocked Text TopLeftText ColWidth EntryRC FormulaLocal FormulaRC HdrWidth LogicalRC NumberFormat NumberSRC RowText TextRC VAlign EnableProtection EntrySRC FormulaLocalRC FormulaSRC HdrHeight LogicalSRC NumberFormatLocal ProtectionHidden RowHeight TextSRC WordWrap

Inserting Multiple Worksheets

You can insert more than one sheet at a time and at any point in the sheet tab index. The number and position of the inserted sheets depends on number and position of the selected sheets in the workbook.

Chapter 4 Workbook Fundamentals

53

To insert worksheets using the Workbook Designer:

1. Select the worksheet immediately to the right of where you want to insert the new worksheets. 2. Select as many worksheets to the right of that worksheet as the number of worksheets you want to insert. For example, to insert two worksheets, select two worksheets. 3. Select Insert > Worksheet. The following illustration shows this process:

Since Sheet2 and Sheet1 are selected, two additional worksheets are inserted to the left of Sheet2. Notice that the newly inserted worksheets are given the next available sheet names, regardless of their position in the sheet index list.

To insert sheets programmatically:

s

Use the NumSheets property to increase the number of worksheets in the workbook. Additional worksheets are added to the right of all existing worksheets. Use the InsertSheets method to add worksheets to the left of a specified worksheet. The following example illustrates how this method can be used to insert 2 worksheets to the left of the third worksheet in the workbook:
F1Book1.InsertSheets 3, 2

Use the SheetSelected property to select the number of worksheets you want and then use the EditInsertSheets method. The following example selects the third and fourth worksheets in the workbook and inserts two worksheets before the third worksheet.
F1Book1.SheetSelected (3) F1Book1.SheetSelected (4) F1Book1.EditInsertSheets

54

Formula One ActiveX Users Guide

Deleting Worksheets
You can delete one or more worksheets from the sheet index list through the Workbook Designer or through application code.

To delete worksheets in the Workbook Designer:

1. Select the worksheets you want to delete. 2. Select Edit > Delete Sheet. The following illustration shows this process:

The selected worksheets are deleted.

To delete worksheets programmatically:

Two methods delete worksheets: DeleteSheets and EditDeleteSheets. DeleteSheets takes arguments that define the position and number of worksheets to be deleted. EditDeleteSheets deletes the currently selected worksheets.
s

Use the NumSheets property to decrease the total number of worksheets. Worksheets are deleted from the right. Use the DeleteSheets method to delete specific worksheets. The following example uses this method to delete the third and fourth worksheets from the workbook:
F1Book1.DeleteSheets 3, 2

Use the SheetSelected property to select sheets and then use the EditDeleteSheets method. The following example selects the first and fourth worksheets and then deletes them:
F1Book1.SheetSelected (1) F1Book1.SheetSelected (4) F1Book1.EditDeleteSheets

Chapter 4 Workbook Fundamentals

55

Renaming Worksheets
Formula One provides a default name for each worksheet. You can change the names to more meaningfully describe the sheets contents. For example, the sheet names in the following illustration are more descriptive than the worksheets default names.

Type a new name in the Sheet Name dialog box.

Double-click the sheet tab to display the Sheet Name dialog box.

To name a worksheet in the Workbook Designer:

1. Select Format > Sheet > Properties and select the General tab. 2. Type a name for the sheet in the Name text box. 3. Click OK.

To edit a sheet name programmatically:

s

Use the SheetName property to rename a worksheet identified by index. The following code changes the name of the second worksheet in the workbook to QTR 2 Sales.
F1Book1.SheetName (2) = "QTR 2 Sales"

Setting Display Options for Worksheets

Just as you can display or hide different parts of the Workbook Designer, you can display or hide different parts of worksheets. You may hide the column and row headings and the gridlines. You may display the worksheet at regular size, shrunk down, or enlarged. You may also choose how many rows and columns you want to display. The default number of rows and columns displayed is the maximum (65,536 rows by 256 columns). You may display fewer. Rows and columns beyond the display limits you specify will not be seen, but they can hold data and formulas.

56

Formula One ActiveX Users Guide

Finally, you may specify how you want to display formulas and zero values.

To change display options for worksheets in the Workbook Designer:

1. Select the worksheet(s) whose display settings you want to change. 2. Select Format > Sheet > Properties and click the View tab. The View tab will appear, as shown below.

To display zeroes in cells, select this option. To leave cells with zero values empty, unselect this option.

To display formulas, select this option. To display values that the formulas calculate, uncheck this box. When formulas are displayed, Formula One automatically doubles the width of columns to accommodate the wider text. When the Formulas option is later unselected, column widths return to their original settings.

3. Select the worksheet and data viewing options you want by selecting or unselecting the options in the Sheet and Data values. 4. To display the worksheet larger or smaller than its actual size, enter a value from 10 to 400 in the View Scale box. 5. To display fewer than the maximum number of rows and columns, enter the range that you want to display, in absolute references, in the Sheet Limits box. 6. Click OK.

To change display options for worksheets programmatically:

s

Use the ShowFormulas, ShowGridLines, ShowZeroValues, ShowRowHeading, ShowColHeading, ViewScale, MaxRow, and MaxCol properties.

Navigating Through Worksheets

When working in the Workbook Designer or in a workbook at run time, you can navigate within individual worksheets using mouse actions or keyboard commands.

Chapter 4 Workbook Fundamentals

57

Navigating with the Mouse

Primarily the mouse is used to select items in a worksheet at run time. The following table lists the mouse actions you can perform in a worksheet at run time or in the Workbook Designer.
Action Left-Click Right-Click Description Moves the active cell to the pointer position. In the containers design mode, brings up the context menu.

Wheel-click (on the Invokes or cancels scrolling mode, which allows users to IntelliPoint mouse) or middle scroll by moving the mouse over the worksheet. To disallow click scrolling mode, hide the scroll bars using the ShowHScrollBar and ShowVScrollBar properties. Left-Click in Row or Column Selects entire row or column. Headings Left-Click in Top Left Corner Selects entire sheet. Left Double-Click in Top Left Displays a dialog box that allows you to enter a label for the Corner, Row Headings, top left corner or the column or row heading, or a new name Column Headings, or for the worksheet that was double clicked. Worksheet tabs Left Double-Click Right Double-Click In the Workbook Designer, invokes in-cell editing. At run time, a DblClick event is fired. In the Workbook Designer, does nothing. At run time, the Workbook Designer is launched if DoRDblClick is False. Left-Click and Drag Selects a range. If other ranges are selected, the previously selected ranges are unselected.

CTRL + Left-Click and Drag Selects a range. If other ranges are selected they remain selected. SHIFT + Left-Click and Drag Extends the current selection. CTRL + SHIFT Click on Row Selects the row headings, column headings, or top left corner Headings, Column Headings, of the sheet. or Top Left Corner Drag a Selection's Copy Handle Drag a Selections Border ALT + Click and Drag an Object or Objects Selection Handles Copies the selection into the newly selected area. Moves the selection to a new location. Repositions or resizes an object and aligns object sides with the cell grid.

58

Formula One ActiveX Users Guide

Navigating with the Keyboard

In addition to navigating through worksheets, keyboard commands allow you to perform a variety of other tasks. Keyboard commands allow you to:
s s s s s s s

position the active cell in the worksheet page through a worksheet enter data typed in a cell move the active cell within a selected range enter and exit edit mode recalculate a workbook delete data from a selected cell or range

The tables in this section list the keyboard commands you can use when working in the Workbook Designer or a workbook at run time. The following table lists action keys that allow you to enter and edit data, move the active cell within a selected range, and recalculate the workbook.
Key ENTER Description When in edit mode, accepts the current entry. When a range is selected, and if the EnterMovesDown property is set to True, accepts the current entry and moves active cell vertically to next cell in selection. When in edit mode, accepts the current entry. When a range is selected, and if the EnterMovesDown property is set to True, accepts the current entry and moves active cell vertically to previous cell in selection. When in edit mode, accepts the current entry and moves the active cell horizontally to right. When in edit mode, accepts the current entry and moves the active cell horizontally to left. Enters edit mode. While in editing mode, F2 displays the Cell Text dialog box, in which you can enter multi-line data entries. Recalculates workbook. May clear current selection depending on the setting of the AllowDelete property. Cancels current data entry or editing operation.

SHIFT + ENTER TAB SHIFT +TAB F2 F9 DEL Escape

The following table lists the movement keys that allow you to move the active cell within a worksheet and display different sections of the workbook.
Key Up Arrow Down Arrow Left Arrow Description Moves active cell up one row. Moves active cell down one row. Moves active cell left one column.

Chapter 4 Workbook Fundamentals

Key Right Arrow CTRL Up/Down/Left/Right Page Up Page Down CTRL Page Up CTRL Page Down Home End CTRL Home CTRL End Description Moves active cell right one column.

59

Moves to the next range of cells containing data. If there is no additional data in the direction in which you are moving, moves to the edge of the worksheet. Moves up one screen. Moves down one screen. Activates the previous worksheet in the current workbook. Activates the next worksheet in the current workbook. Goes to first column of current row. Goes to last column of current row that contains data. Goes to row 1 column 1. Goes to last row and column that contains data.

The following table lists the keys that modify the action of the movement keys.
Key Scroll lock SHIFT plus any movement key Description Causes the view window to scroll without changing current selection with all movement keys except Home, End, CTRL Home, and CTRL End. Extends the current selection.

60

Formula One ActiveX Users Guide

Selecting Cells
Many operations require one or more cells to be selected. There are three kinds of selections: a single cell, a range of cells, and multiple ranges of cells (non-adjacent). The following illustration shows the three types of selections.
Single cell selection

Single range selection

Multiple range selection

Selecting Cells with the Mouse

The worksheet cursor is always located on a cell. The cell on which the worksheet cursor is located is called the active cell. The active cell is also a selection or part of a selection. Any data the user enters is always placed in the active cell.
s

To select a range of cells, click and hold the left mouse button and drag through the range you want to select. When a range is selected, it becomes highlighted. To select multiple ranges, press the CTRL key while selecting a range with the mouse. Any previously selected ranges remain selected.

Once a range is selected, you can move the active cell within the range using the ENTER, SHIFT + ENTER, TAB, and SHIFT + TAB keys. When you use these keys to move the active cell, the range remains selected.

Chapter 4 Workbook Fundamentals

61

Selecting Cells with Properties and Methods

The following properties and methods can select ranges.
s

Setting the Selection property removes all current selections and selects a range. The AddSelection method adds a selection to the current selection list. Continue calling AddSelection to create multiple selections.

The following example selects two ranges. The range my_select is selected, which is the name for A1:D4, and then the E5:H8 range is added.
F1Book1.Selection = "my_select" Select A1:D4 F1Book1.AddSelection 5, 5, 8, 8 add e5:h8

In addition, the following properties retrieve information about multiple selections.

s

The value of the SelectionCount property tells you the number of selections. You can use this if a selection is made by the user and you need to determine how many ranges are selected. The value of the Selection property gives you all current selections in the form of a formula (e.g. A1:D4,E5:H8). The SelectionEx property used with the F1RangeRef API object returns the row and column of the specified selection.

The following example returns the value of a specified selection and adds another column to the selection.
Dim sel As F1RangeRef Dim cnt As Integer For cnt = 0 To (F1Book1.SelectionCount - 1) Set sel = F1Book1.SelectionEx(cnt) F1Book1.AddSelection sel.StartRow, sel.StartCol, sel.EndRow, sel.EndCol + 1 Next cnt End Sub

Selecting Rows and Columns

Entire rows and columns can be selected in the worksheet at run time or in the Workbook Designer using the mouse. To select a row or column, position the pointer on the header of the row or column you want to select. When you click the header, the row or column is selected. You can also select all rows and columns in the worksheet. To do this, position the pointer on the top left header and click.

62

Formula One ActiveX Users Guide

Setting Selection Options

You may prevent users of your worksheet from selecting cells and/or objects. You may also choose to display the worksheet in row mode, which specifies that an entire row be selected when a user selects a cell in that row. Row mode is a nice feature in applications where each row represents a particular record: it makes it obvious which row the user is currently working on and facilitates copying and pasting entire rows.

To set selection options in the Workbook Designer:

1. Select the worksheet(s) whose selection options you want to change. 2. Select Format > Sheet > Properties and click the Selection tab. The Selection tab, displayed below, will appear.

To prevent users from selecting cells, rows, columns, graphical objects, or worksheets, uncheck this option. To prevent users from selecting graphical objects, uncheck this option.

To specify that the entire row should be selected whenever an individual cell in that row is selected, check this option.

3. Choose the selection options you want. Click OK when you are done.

To set selection options programmatically:

s

Use the AllowSelections, AllowObjSelections, and RowMode properties.

Chapter 5 Working With Data

63

C H A P T E R

Working With Data

Entering and manipulating data is the basis for nearly all work performed in a workbook control. You can enter virtually any type of data and formula. With formulas and built-in functions, you can evaluate and calculate that data and make decisions based on the results of those operations. This chapter discusses:
s

how to enter data directly or with methods and properties how to use autofill lists the types of constant values that can be entered how to construct and use formulas the suite of built-in worksheet functions using names the methods for calculating worksheets how to limit user data entry

Understanding Worksheet Data Entry

One of the basic tasks encountered when working with a workbook is data entry. Formula One provides several methods for entering data.
s

Direct entry. This is the most direct method of data entry. Data can be entered directly in a worksheet at run time. Or, you can enter data in the Workbook Designer at design time. Properties and methods. Several properties and methods allow you to enter data in the active cell or a specified cell.

64

Formula One ActiveX Users Guide

Adding the Formula Bar

You can enter data into a worksheet by typing directly into a cell, or by typing into the formula bar.
Formula Bar

Cell Reference Indicator

The formula bar appears by default in the Workbook Designer, and you can turn on or off the display of the formula bar and cell reference indicator in your workbook control.

To control the display of the formula bar in the Workbook designer:

s

Select View > Formula Bar to toggle the display of the formula bar.

To add a formula bar to your control:

s

Set the ShowEditBar property to True. If the ShowEditBar property is True, you can also set the ShowEditBarCellRef to True to display the cell reference indicator with the formula bar.

Important The formula bar does not appear on the control unless the container makes it UI Active (provides a window for it).

Entering Data with Properties

Formula One provides a full complement of properties for entering data. In addition to entering data in the active cell, a number of methods allow you to enter data in a cell you specify. The following table lists the properties involved in entering data.
Property/ Method Entry EntryRC EntrySRC FormattedText FormattedTextRC Description Sets or returns the value of the current cell in edit mode format. Sets or returns the value of the specified cell in edit mode format. Sets or returns the value of the specified cell in edit mode format. Sets or returns the value of the current cell as it appears in the worksheet. Returns the value of the specified cell as it appears in the worksheet.

Chapter 5 Working With Data

Property/ Method Description

65

FormattedTextSRC Sets or returns the value of the specified cell as it appears in the worksheet. Formula FormulaLocal FormulaLocalRC Sets or returns the formula in the active cell. Sets or returns the text version of the formula in the active cell, in the users language. Sets or returns the text version of the formula of the specified cell, in the users language.

FormulaLocal SRC Sets or returns the text version of the formula of the specified cell, in the users language. FormulaRC Logical LogicalRC Logical SRC Number NumberRC Number SRC Text TextRC TextSRC Sets or returns the formula in the specified cell. Sets or returns the formula in the active cell. Sets or returns the logical value of the specified cell. Sets or returns the logical (True or False) value of the specified cell. Sets or returns the numeric value of the active cell. Sets or returns the numeric value of the specified cell. Sets or returns the numeric value of the specified cell. Sets or returns the text value of the active cell. Sets or returns the text in the specified cell. Sets or returns the text value of the specified cell.

Entering Multi-Line Data

A single cell can contain as many as nine lines or 256 characters of data. When entering the data, new lines of data are specified within the cell by entering carriage return/line feeds.
s

When entering data interactively in the Workbook Designer or in a worksheet at run time, press F2 when editing a cell. The Cell Text dialog box is displayed in which you can enter the cell data. To enter a line feed, press RETURN. Click the OK button to accept the entry and return to normal worksheet editing. When entering data with properties or methods, you should specify line feeds with the ANSI character code 10.

After entering multi-line data, you may need to resize the row and column in which the entry is placed in order to view all the data. The following example uses the TextRC property to enter three lines of data in cell A1.
F1Book1.TextRC(1,1) = Regional Sales & Chr$(10) & FY 94 & Chr$(10) & Q2

66

Formula One ActiveX Users Guide

The following illustration shows the results of this example.

The multi-line entry is placed in cell A1. Row 1 and column A have been resized so the entry is not cropped.

You can also enter multi-line row and column headers. Refer to Formatting Row and Column Headings in Chapter 7 for information about entering and formatting row and column headers.

Understanding Worksheet Data Types

Cells can contain two types of information: constant values and formulas.
s

Constant values are numbers (including dates and times), logical values, error values, and text. Formulas are groups of constant values, cell references, names, functions, and operators that result in a new value when calculated or evaluated.

Entering Constant Values

Numbers. Numeric entries can contain numeric characters (e.g., 1, 2, 3, 4, 5, 6, 7, 8, 9, and 0) and the special characters (e.g., +, -, (, ), /, $, %, ., E, and e).
s

Negative numbers can be preceded by a minus sign or enclosed in parentheses. Commas can be included in numeric entries as thousands separators. Numeric entries containing leading dollar signs (or other currency signs, such as for pounds) are formatted as currency. Numeric entries containing trailing percent signs are formatted as percentages.

Formula One accepts numeric entries as fractions. If the fraction contains a leading integer (e.g., 1 1/3) it can be entered directly. If there is no leading integer, the fraction should be preceded by a zero (e.g., 0 2/3). Numbers larger than the cell in which they are entered are converted to scientific notation unless a specific format is applied. Use the SetColWidthAuto method to automatically set the column width to the correct size for all data in the column. The following code automatically sets the widths of columns 1 through 10.
F1Book1.SetColWidthAuto -1, 1, -1, 10, False

Chapter 5 Working With Data

67

Dates and Times. Dates and times are automatically recognized by Formula One. They are entered in the cell as values and automatically formatted. The following date and time formats are automatically recognized.
Entered 3/15/94 15-Mar-94 15-Mar Mar-94 9:55 PM 9:55:33 PM 21:55 21:55:33 3/15/94 21:55 Format Assigned m/d/yy * d-mmm-yy d-mmm mmm-yy h:mm AM/PM h:mm:ss AM/PM h:mm h:mm:ss m/d/yy h:mm *

* These formats are locale-dependent. For example, in the United Kingdom, 15/3/94 would be recognized as the date format d/m/yy. Text. Text is any set of characters that Formula One does not recognize as a number, date, or time. Text that is wider than a cell ordinarily spills over into the cell immediately to the right. You can specify that text should wrap within the cell by enabling word wrap in your alignment format settings. Logical and Error Values. Logical and error values are not normally entered directly in cells; they are usually the result of a formula. However, entering these values can be useful for testing formulas. The logical values that can be entered are TRUE and FALSE. The error values that can be entered are #N/A, #VALUE!, #REF!, #NULL!, #DIV/0!, #NUM!, and #NAME?.

Entering Formulas
Formulas are the basic building blocks for analyzing and calculating worksheet data. A formula is a string containing numbers, operators, worksheet functions, cell references, and names. A formula can contain as many as 1024 characters.
s

When you manually enter a formula in a worksheet, you must begin the entry with an equal sign (=). Formula One recognizes this entry as a formula. When entering a formula using the Formula, FormulaRC, and FormulaSRC properties, exclude the leading equal sign. These entities expect strings.

Numbers in formulas can be followed by a percent sign (%). Numbers with trailing percent signs are treated as percentages (e.g., 100% is evaluated as 1).

68

Formula One ActiveX Users Guide

If text is encountered when a number is expected, the text is converted to a number. For example, the formula 1 + 3 returns 4, because 3 is converted to a number. If the text cannot be converted to a valid number (e.g., 1 + Text), #VALUE! is returned. Likewise, if a number is encountered when text is expected, the number is converted to text. The formula The number is &3 converts to the text string The number is 3. The value TRUE always converts to 1; FALSE converts to 0. If a number is encountered when a logical value is expected, a zero is converted to FALSE. All other numbers are converted to TRUE. If text is encountered when a logical value is expected, TRUE is converted to TRUE; FALSE is converted to FALSE. All other text returns #VALUE!. Dates and times are recognized and converted to their serial values. For example, 10/10/94 - 10/1/94 equals 9.

Using Formula Operators

When creating formulas, Formula One provides a set of operators for specifying the type of calculation or evaluation to be performed on the formula data. The following table lists the formula operators.
Operator Type Arithmetic Operator + / * % ^ Text Comparison & = > < >= <= <> Reference :, .., . Description Addition Subtraction Division Multiplication Percentage Exponentiation Concatenation Equal to Greater than Less than Greater than or equal to Less then or equal to Not equal to Range - produces a reference that includes all the cells between the two references (e.g., A1:A5 includes cells A1 and A5 and all cells in between). Union - produces one reference that includes the two references (e.g., A1:A10,C1:C10).

Chapter 5 Working With Data

69

Using Operator Precedence

When combining operators in a formula, Formula One uses a specific order of precedence to calculate the formula. The following table lists the order of precedence for formula operators.
Operator () :, .., . , % ^ * and / + and & = < > <= >= <> Description Parentheses Range Union Negation (single operand) Percentage Exponentiation Multiplication and Division Addition and Subtraction Text concatenation Comparison

Operators of like precedence are evaluated left to right. Parentheses should be used when it is necessary to change the order of evaluation. The following example illustrates how the result of a formula can be altered by adding parentheses to change the order of precedence.
Formula 1+2*37 (1+2)*37 Result 75 111

As illustrated in the previous table, the multiplication operator (*) has higher precedence than the addition operator (+). It is evaluated first unless parentheses are used to force the addition to take place first.

Understanding Cell References

A reference identifies a cell by referring to the row and column coordinates of the cell. References are based on the row and column headings. For example, A1 refers to the cell at the intersection of row 1 and column A. References can be used in formulas to access data from a worksheet. A range of cells is specified by placing a colon (:) between two cell references. For example, the reference A1:C3 refers to the range anchored by cells A1 and C3. The range includes all cells in columns A, B, and C of rows 1, 2, and 3.

70

Formula One ActiveX Users Guide

Absolute and Relative References

There are two types of cell references: relative and absolute.
s

Relative references point to a cell based on its relative position to the current cell. When the cell containing the reference is copied, the reference is adjusted to point to a new cell with the same relative offset as the originally referenced cell. Absolute references point to a cell at an exact location. When the cell containing the formula is copied, the reference does not change. Absolute references are designated by placing a dollar sign ($) in front of the row and column that is to be absolute.

References can be part absolute and part relative. These are called mixed references. The following table lists the reference types.
Reference A1 $A$1 $A1 A$1 Type Relative reference pointing to cell A1. Absolute reference pointing to cell A1. Absolute column reference, relative row reference pointing to cell A1. Relative column reference, absolute row reference pointing to cell A1.

The reference operators can be used to specify multiple ranges in the same reference. For example, A1:C1,A10:C10 specifies the three cells A1, B1, and C1 and the three cells A10, B10, and C10. The formula =SUM(A1:C1,A10:C10) adds the values in all six cells.

References to Other Worksheets

You can reference cells in other worksheets in the same or different workbooks. To reference a worksheet in the same workbook, use the following syntax:
Sheet3!A1

To reference a worksheet in a different workbook, use the following syntax:

[F1Book1]Sheet1!A1:B2

Workbooks are referenced by the value of their Title property, and must be loaded in another control for the reference to work.

References to Multiple Worksheets

You can also refer to multiple worksheets, or ranges in multiple worksheets. The following example references cell A1 in Sheet1 and cell A1 in Sheet2.
Sheet1:Sheet2!A1

Chapter 5 Working With Data

71

Important Worksheets must be referenced in index order. For example, the reference to the sheet indexed 1 must come before the reference to the sheet indexed 2. Remember that the worksheet index is usually different that the sheet name that appears on the sheet tab. Worksheets are indexed from left to right, beginning with 1. The following syntax references the range A1 to B2 in Sheet1 and the range A1 to B2 in Sheet2.
Sheet1:Sheet2!A1:B2

You can also reference multiple worksheet ranges in different workbooks by referencing the workbook name at the beginning of the syntax.
[F1Book1]Sheet1:Sheet2!A1 [SSView2]Sheet1:Sheet2!A1:B2

External References
References can point to cells in other workbooks. This type of reference is called an external reference. An external reference is created by placing a workbook name in brackets, followed by the worksheet name and an exclamation point, and finally a cell reference. The following table shows examples of external references.
Reference [Sales]Sheet1!A1 [FY91]Sheet2!$A$1 [Q1]Sheet1:Sheet2!$A1 Type Relative reference pointing to cell A1 in the first worksheet of a workbook titled Sales. Absolute reference pointing to cell A1 in the second worksheet of a workbook titled FY91. Absolute column reference, relative row reference pointing to cell A1 in the first and second worksheets in a workbook titled Q1. Relative row and column reference, pointing to the range A1 to F1 in a workbook titled Store1.

[Store1]Sheet1:Sheet4!A1:F1

Automatically Entering Cell References

Cell references can be automatically entered as you enter a formula.

To automatically enter a cell reference:

1. Enter the formula to the point of the range reference. 2. With the mouse, select the cell or range you want to reference. The reference of the range you select is automatically placed in the formula. When you enter a cell reference in this manner, Formula One assumes it is a relative reference.

72

Formula One ActiveX Users Guide

Understanding Worksheet Errors

When a formula cannot be properly calculated, an error is returned in the cell. The following table lists the errors that can be generated.
Error #ARRAY_FORMULA! Cause Formula One read an Excel file that contained an array formula. Since this feature is not supported in Formula One, this error value is placed in the cell that used to contain the array formula. Divide by zero. May be caused by a reference to a blank cell or a cell containing zero. No value is available. May be caused by inappropriate values in the formula or a reference to a cell containing the #N/A value. Name is not recognized. May be caused by a user defined name that is not defined. Null intersection. An intersection of two ranges was defined that does not intersect. Number problem. May be caused by inappropriate numbers in functions, an iteration that cannot solve for a value, or a formula that results in a number too large or too small to represent. Reference error. May be caused by referring to a cell that was deleted. Wrong argument type. May be caused by entering text where a number was expected, or supplying a range to an operator or function that was expecting a single value.

#DIV/0! #N/A #NAME? #NULL! #NUM!

#REF! #VALUE!

Displaying Formulas
It is often convenient to display formula text instead of the values they produce. Setting ShowFormulas to True, causes the worksheet to display formula text instead of formula results. Displaying formula text can help you debug formula- related problems. The following example enables and disables the display of formulas.
F1Book1.ShowFormulas = TRUE Displays formulas F1Book1.ShowFormulas = FALSE Displays formula text

Built-In Worksheet Functions

Formula One contains a set of 143 built-in worksheet functions that provide the ability to perform complex calculations with very little work.

Chapter 5 Working With Data

73

Worksheet functions:
s

calculate and evaluate data can be used alone or in a formula are entered directly in the worksheet

Like formulas, worksheet functions return data to the cell in which they are entered. Each function performs a specific calculation. The SQRT function is an example of a built-in function. With this function, you can easily calculate the square root of a number. The following example calculates the square root of 118:
=SQRT(118)

Understanding Functions
Most worksheet functions are composed of keywords and arguments. Every worksheet function contains a keyword, but not all functions require arguments.
s

The keyword identifies the function and tells the worksheet what type of calculation or evaluation is performed. Each function keyword is unique. Arguments provide the data for the function to calculate or evaluate. The arguments for a function immediately follow the function keyword and are enclosed in parentheses.

Entering Functions
When entering functions in a worksheet, all functions are preceded by an equal sign (=). The leading equal sign tells the worksheet that the following information is to be evaluated or calculated. The function keyword follows the equal sign. It can be entered in lowercase or uppercase characters. After the function is entered, the worksheet records the function keyword in uppercase characters, regardless of how it was entered. If a function requires multiple arguments, the arguments are separated by commas. Some functions contain optional arguments. If you omit an optional argument, a default value is assumed for the argument. Functions that do not require arguments still require a set of parentheses following the function keyword.

Nesting Functions
A function can be used as an argument for another function. When a function is used in this manner, you are nesting functions. The nested function must return the appropriate type of data for the function in which it is nested. You must also provide the necessary arguments for the nested function.

74

Formula One ActiveX Users Guide

In the following example, the AVERAGE function is used as an argument for the SUM function. In this case, AVERAGE is nested in SUM.
=SUM(5.23, 6.82, AVERAGE(2.45, 5.62, 7.74), 8.95, 9.01)

Entering Arguments
The arguments for a function can be:
s

Numerical values Logical values Text strings Error values References to cells or ranges

Each argument requires a specific type of data. Refer to Chapter 14, A-Z Worksheet Function Reference, to determine the type of data required for the function you are entering. For most arguments, you can substitute a cell or range reference for the data required by an argument. For example, if an argument requires a number, you can substitute a reference to a cell that contains a number. The number in the referenced cell is used in the calculation of the function. The data in the referenced cell must be appropriate for the argument for which it is used.

Syntax Errors
If the worksheet function you enter contains syntax errors, Formula One does not allow the function to be entered. You must correct the errors before proceeding with other tasks.

Using Autofill Lists

If you frequently use lists of names, months, or days of the week in your worksheet, you can let Formula One do some of the work for you by using the autofill feature. Formula Ones default autofill lists contain frequently used series of text such as months and days of the week. When you enter one of the elements in these lists and drag the autofill handle, Formula One enters the rest of the data from the list as needed to fill the range you mark.
When Formula One recognizes this text as part of an autofill list, and . . . you drag the fill handle to this position, the cells in the marked range are automatically filled with items from the list.

Chapter 5 Working With Data

75

Once Formula One has recognized the text as an item from an autofill list, pressing Tab puts the next list item in the next cell to the right, or Enter puts the next list item in the next cell below.

Adding Autofill Lists

You can add custom autofill lists that include frequently used series of text with the AutoFillItems property. You can also access the AutoFill tab using the OptionsDlg method (F1AutoFillPage).

To add a new autofill list using the AutoFillItems property:

s

Use the AutoFillItemsCount method to determine the number of autofill lists. Then increment by one and use the AutoFillItems property to specify the new list. The following example illustrates:
F1Book1.AutoFillItems (F1Book1.AutoFillItemsCount+1) = "A;B;C;D;E;F;G;H;I;J;K;L;M;N;O;P;Q;R;S;T;U;V;W;X;Y;Z"

Note Values recognized as data cannot be used as autofill list items, such as 1973;1974, 1a;1b, 1%;2%.

To add a new autofill list using the OptionsDlg method:

1. Use the following code:
F1Book1.OptionsDlg (F1AutoFillPage)

2. The following dialog box is displayed:

When (New List ) is selected, you can type your custom list in the Current List text box. You can also edit default lists using this text box.

3. Select (New List) from the Lists list. 4. Type your new autofill list in the Current List text box, separating each item with a semi-colon. 5. Click Add.

76

Formula One ActiveX Users Guide

Deleting Autofill Lists

You can delete an autofill list using the AutoFill tab by selecting a list and clicking the Delete button. You can also delete a default or custom autofill list using the DeleteAutoFillItems method.

To manipulate an autofill list programmatically:

s

Get the current string of text that makes up a list by returning the value of the AutoFillItems property.
list = F1Book1.AutoFillItems(2)

Replace a list by setting the AutoFillItems property.

list = "1st Qtr;2nd Qtr;3rd Qtr;4th Qtr" F1Book1.AutoFillItems(2) = list

Delete a list with the DeleteAutofillItems method.

F1Book1.DeleteAutoFillItems (F1Book1.AutoFillItemsCount -2)

Using Names
User-defined names are an easy way to identify a cell, a group of cells, a value, or a formula. For example, the formula = Sales - Expenses is much clearer than A10 - A6. You can also use names to identify constants and formula expressions. For example, you might define the name LightSpeed as 186000. You could then use the name LightSpeed in all your formulas. Or, you could define the name SqRtTwo as the formula SQRT(2).

To define names in the Workbook Designer:

1. If you are naming a range, select it. 2. Select Insert > Name. 3. Enter a name that describes the cell reference in the Name text box. Do not use spaces in the name. A cell or range reference that represents your selection from step 1 is displayed in the Formula text box. You can edit this reference, if desired. 4. Click Add to add the new name to the list. You can delete any name from the list by selecting it in the list and clicking Delete.

To define names programmatically:

s

Use the DefinedName property. The following code uses this property to define a name.

F1Book1.DefinedName ("Sales") = "$A$10"

Chapter 5 Working With Data

77

This example defines the name Sales as $A$10. The name Sales can then be used in formulas instead of the reference. Formula One has a set of built-in names. These names are used by the print functions. The built-in names are listed in the following table.
Built in Name Print_Area Print_Titles Purpose Defines the print area used during printing. This name can contain one or more ranges (e.g., A1:C3,A11:C13). Defines the row and column titles that are printed on each new page. Entire rows and columns must be selected when you define this name.

Calculating Worksheets
Formula One calculates cells in natural order. In natural order calculation, formulas are calculated in such a way that all dependencies are calculated before their dependents. This ensures that the formula results are always correct. When a worksheet is edited, Formula One first adjusts formula references so they point to the correct cells. Then, Formula One determines the natural order of the formulas. When a change is made to a cell, the formulas are recalculated to keep all worksheets in the workbook current, ensuring that data is always valid.

Setting Automatic Recalculation

Normally, automatic recalculation is enabled, which means the worksheet is recalculated each time a cell is changed and system processing is idle. For moderately sized worksheets, recalculation operations happen in a fraction of a second. But for large worksheets or situations where many cells are changed by code, this reorganization and recalculation process can slow system processing. In these situations, you may disable automatic recalculation while your code operates on the worksheet. After the operation is completed, you may enable automatic recalculation to update the worksheet. Automatic recalculation can be disabled using the Workbook Designer or with the AutoRecalc property or the OptionsDlg method.

78

Formula One ActiveX Users Guide

To change automatic recalculation using the Workbook Designer:

1. Select Tools > Options and click the Calculation tab, shown below.
Uncheck this option to disable automatic recalculation.

2. Select the Automatic Recalc option to turn auto recalc on, or unselect it to turn it off. 3. Click OK.

To change automatic recalculation programmatically:

s

The following code uses the AutoRecalc property to disable the automatic recalculation setting.

F1Book1.AutoRecalc = FALSE Disables automatic recalculation

Setting Minimal Recalculation

Minimal recalculation means that, when Formula One needs to recalculate the formulas on the worksheet, it only recalculates cells that refer to cells that have changed. Cells and references to cells that have not changed are left alone. This will often cause a dramatic improvement in recalculation speed. By default, minimal recalculation is on. When minimal recalculation happens is determined by the setting of the AutoRecalc property. When AutoRecalc is set to True, minimal recalc will be called whenever the worksheet changes. If AutoRecalc is off, minimal recalc will be called when the user presses F9 or uses the Recalc method. The CALL, COLUMNS, INDEX, INDIRECT, NOW, OFFSET, RAND, ROWS, and TODAY worksheet functions must be reevaluated during every recalc to ensure accurate results. Formulas that use these functions are reevaluated during every recalc operation regardless of whether minimal recalc is on or off. You may encounter an unusual instance where minimal recalculation slows worksheet processing speed. In these cases, you may want to turn minimal recalculation off.

Chapter 5 Working With Data

79

To change minimal recalculation in the Workbook Designer:

1. Select Tools > Options and click the Calculation tab, shown on page 78. 2. Select the Minimal Recalc option to turn minimal recalc on, or unselect it to turn it off. 3. Click OK

To change minimal recalculation programmatically:

Use the MinimalRecalc property.

Solving Circular References

In some circumstances, a formula refers to its own cell, either directly or indirectly. This is called a circular reference. To solve a formula that contains a circular reference, iteration must be used. Iteration is the process of repeatedly calculating a worksheet until a specific condition is met. Formula One supports iteration using the IterationEnabled, IterationMax, and IterationMaxChange properties; the GetIteration and SetIteration methods; and the OptionsDlg (F1CalculationPage) method. These properties and methods allow you to specify the maximum number of iterations and the maximum change between iterations. The iteration continues until one of those two conditions is met. The following example involves a circular reference: Suppose your small business has 10,000 shares of stock owned by four shareholders. You decide to let a fifth shareholder enter your partnership. In return for his investment, you give him 10 percent of the company. How many more shares will the company have to issue to give the new investor 10% of the company? The following illustration shows the results of this example as it is entered in a worksheet.
The formulas in B2 and B3 create a circular reference in this example worksheet. The first worksheet shows the formula text, the second worksheet shows the results of the formulas.

To control the number of times a circular reference is calculated using the

Workbook Designer: 1. Select Tools > Options and select the Calculation tab, shown on page 78. 2. Click the Iteration check box to limit iteration for calculating circular references.

80

Formula One ActiveX Users Guide

3. In the Maximum Iterations text box, type the maximum number of iterations you want Formula One to execute. 4. In the Maximum Change text box, type the maximum change between iterations. The smaller the number, the more accurate your answer is. 5. Click OK.

Limiting Data Entry

Some applications might require that the user not be allowed to enter or edit data. Formula One gives you many options for restricting data entry.

Denying Access to a Workbook

You may make an entire workbook and all the worksheets in it read-only. Any data manipulation in such a workbook must be done programmatically. You may deny access to a workbook using the Workbook Designer or using properties and methods

To use the Workbook Designer to make a workbook read-only:

You must hide the formula bar and disable all of the users editing options. 1. To hide the formula bar, select View > Formula bar. Make sure the option is unselected. 2. To disable users editing options, first select all the worksheets in the workbook. 3. Choose Format > Sheet > Properties and click on the Edit tab. The Edit tab, shown below, will appear.

4. Unselect the following options: Enable Delete Key, Enable In-Cell Editing, Enable Cell Text Dialog, and all of the options in the Allow User To box. 5. Click OK.

Chapter 5 Working With Data

81

To use properties and methods to make a workbook read-only:

s

Set all of the following properties to False: ShowEditBar, AllowDelete, AllowInCellEditing, AllowCellTextDlg, AllowResize, AllowFillRange, AllowMoveRange, AllowEditHeaders, and AllowFormulas. Data and formula entry and editing is thus prevented. Any data manipulation must be performed programmatically.

Denying Access to a Worksheet

To deny access to a worksheet, hide the worksheet tabs. For information on how to do this in the Workbook Designer and programmatically, see Displaying Parts of the Workbook Designer on page 45.

Denying Access to Certain Cells

To deny access to one, a few, or all of the cells in a worksheet, lock the cells and enable worksheet protection. Locked cells may be selected, but they cannot be changed, moved, resized, or deleted. You may protect the entire worksheet or just certain cells in the worksheet. You can protect the worksheet in the Workbook Designer or programmatically. Protecting the worksheet is a two-step process: First you choose which cells you want to be locked. Then you enable worksheet protection. Locking the cells has no effect until you enable the protection. By default, worksheet cells are locked and protection is disabled.

To protect the worksheet in the Workbook Designer:

1. Select the cells you want to lock or unlock. 2. Select Format > Cells and click the Protection tab. The Protection tab of the Format Cells dialog box appears. 3. Check the Locked check box to lock the selected cells. Uncheck the Locked check box to unlock the selected cells. Click OK. 4. Select Format > Sheet > Protection. A check by the Protection menu item means that protection is enabled and locked cells cannot be entered and changed.

To set editing permissions on selected cells programmatically:

1. Select the cells you want to lock and use the GetCellFormat or SetCellFormat method of the F1Book object to create an F1CellFormat object for the selected cells. 2. Use the ProtectionLocked property of the F1CellFormat object to lock or unlock the selected cells. (Note: You can use the ProtectionHidden property of the F1CellFormat object to hide cells.) 3. Use the EnableProtection property to enable protection.

82

Formula One ActiveX Users Guide

Note Worksheet cells are locked by default. If you want to protect only selected cells, you must unlock the rest of the worksheet cells, then enable worksheet protection.

Working With Locked Cells

By default, in the Workbook Designer, when a user selects a locked cell and tries to enter data, Formula One will beep and display the message Locked cells cannot be modified. You can turn off the error message so that Formula One just beeps in this situation. To turn off the error message, uncheck the Show Locked Cells Error Message in the Edit tab of the Format Sheet dialog box. To turn off the error message programmatically, set the ShowLockedCellsError property to False. Also in the Workbook Designer, when a locked cell is selected, the ENTER, SHIFTENTER, TAB, and SHIFT-TAB keys advance the selection to the next unlocked cell.

Denying Access to Row and Column Headings

You may keep the user from changing row and column heading text in a worksheet.

To use the Workbook Designer to deny access to row and column headings:
1. Select the worksheet(s) you want to restrict access to headings in. 2. Choose Format > Sheet > Properties and click the Edit tab. The Edit tab, shown on page 80, will appear. 3. Uncheck the Edit Headings box and click OK.

To use properties to deny access to row and column headings:

s

Set the AllowEditHeaders property to False.

Restricting Cell Data to Certain Values

You can restrict the user to entering only specific values in a cell by specifying a validation rule for the cell. A validation rule consists of a formula to test, and text to display if the validation fails. If the formula returns True, the value is entered. If the formula returns a text string, the string is displayed and the value is not entered. If the formula returns False, the value is not entered and the validation text is displayed in an error dialog box. For example, you can limit the range of values a user can enter in a cell by creating a rule that fails if the user enters a number under 100 and displays the message Enter a value greater than 100. You can use relative references in validation rules. These references are considered to be relative to the active cell. This allows a validation rule to be properly applied to an entire range.

Chapter 5 Working With Data

83

Note Validation rules are only checked if data is entered manually, or through use of the Entry or EntryRC property. Any other way of entering data, such as selecting a value from a check box, bypasses validation.

Note Formula Ones validation rules are incompatible with Microsoft Excels validation rules.

To create a validation rule in the Workbook Designer:

1. Select the cell for which you want to create a validation rule. 2. Select Format > Cells to display the Format Cells dialog box. 3. Select the Validation tab. 4. Enter a validation formula in the Rule text box. 5. Enter text to be displayed if the data fails the validation test in the Text box. 6. Click OK.

This illustration shows the validation rule created for cell A1.

84

Formula One ActiveX Users Guide

This illustration shows the message displayed when the data entered in cell A1 fails the validation rule.

To work with validation rules programmatically:

s

Use the ValidationRule property of the F1CellFormat object to create, edit, or return the validation rule associated with the specified cell. (You can also use the ValidationRuleLocal, ValidationRuleRC, and ValidationRuleLocalRC properties to set or return validation rules.) Use the ValidationText property of the F1CellFormat object to create, edit, or return the text to be displayed if the validation rule fails. Use the FormatCellsDlg method to display the Format Cells dialog box. For example, to only display the Validation tab of the Format Cells dialog box, use the following code:
F1Book1.FormatCellsDlg (64)

Use the ValidationFailed event to respond progammatically when data fails. You can even change the value of the data within the ValidationFailed event and attempt to re-validate.

All of these properties, methods, and events are documented in detail in the Formula One Online Documentation.

Chapter 5 Working With Data

85

The Validation Formula

The validation formula follows basically the same rules as those for defined names (see Using Names on page 76). It must also be a worksheet formula that evaluates to True or False. Following are a number of examples of validation formulas.
SUM(A6:A7) > A5 AND(A6>1, A6 <100) IF (A7>1,A7<100,A7>0) OR(ISLOGICAL (A7), A7=1,A7=0)

Denying Entry of Formulas in a Worksheet

You may prevent users from entering formulas in a worksheet while still allowing them to enter constant values. You may do this in the Workbook Designer or through code.

To use the Workbook Designer to deny users the ability to enter formulas:
1. Select the worksheet(s) in which you dont want users to enter formulas. 2. Choose Format > Sheet > Properties and click the Edit tab. The Edit tab, shown on page 80, will appear. 3. Uncheck the Enter Formulas box and click OK.

To use properties and methods to deny users the ability to enter formulas:
s

Set the AllowFormulas property to False. Setting this property to False does not affect the entry and editing of constant values.

Restricting the Use of Certain Keys

You may enable and disable a variety of navigation and data entry keys for particular worksheets. You may do this in the Workbook Designer and in code.

To use the Workbook Designer to disable the use of certain keys:

1. Select the worksheets to which you want to apply the changes. 2. Select Format > Sheet > Properties and click the Edit tab. The Edit tab, shown on page 80, will appear. 3. To disable use of the arrow, delete, and/or tab keys, unselect the Enable Arrow Keys, Enable Delete Key, and/or Enable Tab Key options. 4. To prevent the Cell Text dialog box from appearing when the user presses F2 twice, unselect the Enable Cell Text Dialog option. (The Cell Text dialog allows the user to enter multi-line data.) 5. To leave the active cell selected when a user presses Enter, unselect the Enter Moves Down option. To move the active cell down one row when the user presses Enter, check the enter Moves Down box. 6. Click OK.

86

Formula One ActiveX Users Guide

To use properties and methods to disable the use of certain keys:

1. Use the following properties: AllowArrows, AllowDelete, AllowTabs, AllowCellTextDlg, and EnterMovesDown.

Restricting the Use of Certain Mouse Actions

For any of the worksheets in a workbook, you can prevent the user from resizing cells and headings, from filling a range of cells by dragging with the mouse, and from moving ranges by dragging. You can prevent these actions using the Workbook Designer or using code.

To use the Workbook Designer to prevent certain mouse actions:

1. Select the worksheet(s) that you want to deny access to mouse actions to. 2. Select Format > Sheet > Properties and click the Edit tab. The Edit tab, shown on page 80, will appear. 3. To keep users from changing the size of rows, columns, and row and column headings, unselect the Resize Rows, Columns, and Headings option. 4. To keep users from filling a range by dragging, unselect the Fill a Range by Dragging option. 5. To keep users from moving a cell or range by dragging, unselect the Move a Range by Dragging option. 6. Click OK.

To use properties to prevent certain mouse actions:

s

Use the AllowResize, AllowFillRange, and AllowMoveRange properties.

Chapter 6 Editing Worksheets

87

C H A P T E R

Editing Worksheets

Formula One provides a variety of ways to edit data in worksheets.

s

You can copy, move, and paste selections interactively or programmatically. Methods allow you to insert data in and delete data from ranges, rows, and columns. A selected range of data can be sorted according to keys that you specify.

Copying, Moving, and Pasting Selections

You can copy, move, and paste selections interactively or programmatically. Selections in a worksheet contain many attributes such as:
s

Formulas. Establish the value in a cell. Formulas are displayed in the formula bar when the cell is active. Values. What displays in the cell. Formats. How the cells and values are shown, such as red text applied to a selection.

Note Formula One maintains its own internal clipboard and also supports text on the Windows clipboard. The internal clipboard is more flexible than the Windows clipboard. The internal clipboard retains formulas and allows cell references to be adjusted when cells are pasted. The Windows clipboard only holds text and formatting; cell references are not maintained by the Windows clipboard.

Using Dragging to Move, Copy, and Paste Selections

If you are moving or copying a selection within the same worksheet, dragging or dragging-and-dropping are the most simple techniques to use. This section discusses how to:
s

copy a selection to the right or down using dragging drag-and-drop a selection to copy or move it

88

Formula One ActiveX Users Guide

Copying a Selection Using Dragging

You can copy a selection to the right or down by dragging the copy handle of a selection. The copy handle is the small knob in the lower right corner of a selection. When you copy data using the copy handle, the pointer changes to a small crosshair. The following illustrations describe how to copy by dragging.

The copy handle appears in the lower right corner of a selection.

In this illustration, the number in A1 is copied to the cells below when the copy handle is dragged downward.

You can also copy a selected range in a worksheet. If an autofill list is defined for the data in the range, the data is copied using the autofill list, as shown in the following illustration.

In this illustration, the cells below the range are filled with the data from the autofill list when the copy handle is dragged downward.

The copy handle was dragged to cell A7.

Moving or Copying a Selection Using Drag-and-Drop

The following steps describe how to move or copy a selection using Formula Ones drag-and-drop. Formula Ones drag-and-drop functionality is different from this type of functionality in other applications. For information about drag-and-drop in other applications, refer to Using Drag-and-Drop with Other Applications on page 90.

To move or copy a selection using drag-and-drop:

1. Select the cells that contain the data, object, or chart you want to move or copy. 2. Position the pointer on the border of the selection.

Chapter 6 Editing Worksheets

89

When placed on the selection border, the pointer changes to an arrow, as shown in the following illustration.

The pointer appears as an arrow when positioned on a selection border.

3. When the pointer changes to an arrow,

s

to move the selection, hold down the mouse button and drag-and-drop the selection to the new location. to copy the selection, hold down the CTRL key and drag-and-drop the selection to the new location

An outline of the selection moves as you drag the pointer, as shown in the following illustration.

When you dragand-drop a selection border, the highlighted area moves to indicate the placement of the selection.

Tip To place the selection on an area of the worksheet that is not visible, move the cursor to the edge of the worksheet and scroll to the appropriate location. 4. When the pointer is at the appropriate location, release the mouse button. The original selection is not moved if you hold down the CTRL key. However, The original selection is moved to the new location if do not hold down the CTRL key. Note You can disable the users ability to copy data by setting the AllowFillRange property to False. This disables interactive data copying.

90

Formula One ActiveX Users Guide

Using Drag-and-Drop with Other Applications

You can easily drag text and Windows metafile pictures onto a Formula One worksheet from other Windows applications, such as Excel. Note The drag-and-drop functionality only works with applications that support Windows CF_TEXT and CF_METAFILEPICT data. The mouse pointer changes to to indicate that the data cannot be placed in the selected location. For example, if you select data and drag it to the Desktop, the pointer indicates that the data cannot be dropped onto the desktop.

To drag information from another application and drop it into Formula One:
1. Arrange the application windows so that the source and destination documents are open and visible. You must be able to see the information you want to drag and the Formula One worksheet you want to place it on. 2. Select the information you want to move or copy.
s

To move the information, point to the selected information, and then hold down the mouse button. When the pointer appears, drag the pointer to the new location, and then release the mouse button. The pointer changes to to indicate a move. To copy the information, hold down the CTRL key, point to the selected information, and then hold down the mouse button. When the pointer appears, drag the pointer to the new location, and then release both the mouse button and the CTRL key. The pointer changes to to indicate a copy.

To drag a selection from Formula One to another application:

1. Arrange the application windows so that the source and destination documents are open and visible. You must be able to see the data on the Formula One worksheet. 2. Select the information you want to move or copy.
s

To move the selection, point to it, and then hold down the mouse button. When the pointer appears, drag the pointer to the new location, and then release the mouse button. The pointer changes to to indicate a move. To copy the selection, hold down the CTRL key, point to the selection, and then hold down the mouse button. When the pointer appears, drag the pointer to the new location, and then release both the mouse button and the CTRL key. The pointer changes to to indicate a copy.

Chapter 6 Editing Worksheets

91

Using Menu Commands to Move, Copy, and Paste Selections

If you are moving or copying a selection for a longer distance, such as another workbook, worksheet, or application you might want to use menu commands. Also, in some instances you might not want to paste all cell attributes to the other location. Formula One allows you to choose whether to paste formulas, values, or formats. Furthermore, Formula One allows you to copy formatting from a cell or range and apply that formatting to another cell or range. This section describes how to use menu commands to:
s

move, or copy and paste a selection copy formatting of a selection and apply it to a cell or range paste individual attributes of a selection to another location

Formula One also provides toolbar buttons that perform the same functions as the menu commands.

To move or copy a selection using menu commands:

1. Select the cells that you want to cut. 2. Select Edit > Cut to move a selection. Alternatively, select Edit > Copy to copy a selection. 3. Select the upper left cell where you want to move or paste the selection and select Edit > Paste. This pastes all cell attributes.

To paste individual cell attributes:

1. Select the upper left cell of where you want to paste the selection and select Edit > Paste Special. The Paste Special dialog box is displayed as shown in the following illustration:

Select the option button for the attribute that you want to paste.

2. Click OK.

92

Formula One ActiveX Users Guide

To copy only the formatting of a selection and apply it to a cell or range:

1. Select the cells that contain the formatting that you want to apply. 2. Select Edit > Copy Cell Format. 3. Highlight the cell or range for which you want to apply the formatting and click the left mouse button. The formatting is applied.

Using Methods to Edit, Move, Copy, and Paste Selections

Selections can be edited, moved, copied, or pasted programmatically using the techniques described in the following sections.

Using Methods to Edit Ranges

Ranges of data can be edited using one of several editing methods. Formula One automatically adjusts cell references when cells are moved. Thus, the integrity of worksheet formulas remains intact. The following table describes the methods that interact with the clipboards.
Method ClearClipboard CopyAll EditCopy Operation Frees Formula One resources that are on the Windows clipboard. Copies the contents of the active worksheet in the specified view to the active worksheet in the current view. Copies the current selection to the internal clipboard and the Windows clipboard (in text format only). If there is more than one selection, only the first selection is copied. Cuts the current selection to the internal clipboard. If there is more than one selection, only the first selection is cut. Pastes the contents of the internal clipboard to the current selection. If the internal clipboard is empty, text is pasted from the Windows clipboard. You can also paste tab-delimited blocks of data. Pastes values from the clipboard to the current worksheet selection. Any formatting applied to the values is ignored. In addition, only formula results are pasted; formulas are ignored. Pastes formats, formulas, values, or everything from the clipboard to the selected range.

EditCut EditPaste

EditPasteValues

EditPasteSpecial

If you cut a cell to which formulas refer, the formula references are maintained while the cell remains in the clipboard. If the cell is subsequently pasted, references in the original formulas are adjusted to point to the cells new location. If a cell containing a formula is copied and subsequently pasted, its relative references are adjusted to point to a new location.

Chapter 6 Editing Worksheets

93

Using Methods to Copy Selections Across

Four methods copy selections within and between worksheets. The following table describes these methods.
Method EditCopyDown EditCopyRight CopyRange CopyRangeEx Operation Copies the top row of the selection down. Relative references are automatically adjusted. Copies the left column of the selection right. Relative references are automatically adjusted. Copies a range from one range to another, within the same workbook or between workbooks. Copies a range from one worksheet to another, within the same workbook or between workbooks.

Using Methods to Move Data

There are several ways you can move ranges of data. The easiest way is to use the MoveRange method. When you use this method, the integrity of formula cell references is maintained. If there is special processing that must be performed when data is moved, you can use a loop in C or C++ code to move the data. However, cell references are not adjusted using this technique.

Using Methods to Copy Data Between Worksheets and Arrays

Formula One provides two methods for copying data between a worksheet and a variant array.
s

The CopyDataFromArray method allows you to quickly copy data from an array to a specified range of cells in a worksheet. The CopyDataToArray method allows you to quickly copy data from a specified range of cells in a worksheet to a variant array.

Transferring Data via Uniform Data Transfer

In development environments which support Uniform Data Transfer, Formula One exposes its IDataObject for Uniform Data Transfer support. Data can be transferred between the ActiveX control and other applications that support UDT in the CF_TEXT format. When an application requests data from Formula One, the current selection is sent in tab-delimited format. When CF_TEXT data is sent to Formula One, it is copied into the worksheet starting at Cell A1 unless the DataTransferRange property has been set.

94

Formula One ActiveX Users Guide

Finding and Replacing Data in Formula One

Formula One allows you to find and replace data within a worksheet in formulas and values. You may invoke the Find dialog and a separate Replace dialog in the Workbook Designer or programmatically within the application. You may also find and replace data in a worksheet using properties and methods. Whichever way you choose to do the find and replace, Formula One gives you several search options: You may search by row or by column; you may search for values or formulas or both; and you may specify search options like matching case.

To find data in a worksheet using the Workbook Designer:

1. Invoke the Workbook Designer by selecting that option on the context menu. 2. Choose Edit > Find or issue the Ctrl F keyboard shortcut. The Find dialog, shown below, will appear.

The Find dialog allows you to search for data in a worksheet by row order or by column order.

In a Formula One worksheet, you can search for data in cell Values or Formulas.

3. Enter the data you want Formula One to search for in the Find What dialog box. Choose any special search options you want, then click the Find Next button. 4. Formula One will select the first cell that contains the search string you chose. If it finds no instances of the string, it will display the message "Cannot find matching data." 5. If you want to replace the data, click Replace. The Replace dialog box, shown below, will appear. 6. Click Close when you finish.

To replace data in a worksheet using the Workbook Designer:

1. Invoke the Workbook Designer by selecting that option on the context menu.

Chapter 6 Editing Worksheets

95

2. Choose Edit > Replace or issue the Ctrl H keyboard shortcut. The Replace dialog, shown below, will appear.

The Replace dialog provides a text box for entering the data string you wish to replace with.

Select Match Case if you want the search to find data with matching case. Select Find Entire Cells Only if you want the search to locate cells containing only the string. Otherwise, Formula One will also locate cells that contain the search string and other data.

3. Enter the data you want Formula One to search for in the Find What dialog box. Enter the data you want to replace that data with in the Replace With box. Choose any special search options you want, then click Find Next. 4. Formula One will select the first cell that contains the search string you chose. If it finds no instances of the string, it will display the message "Cannot find matching data." 5. Click Replace if you want to replace the data, or click the Find Next button to search for the next instance of the search string. 6. Click Close when you finish.

To invoke the Find and Replace dialogs programmatically:

s

Use the FindDlg and the ReplaceDlg methods.

To find and replace data in a worksheet using properties and methods:

Formula One provides an API object, F1FindReplaceInfo, to help you programmatically search for data in a worksheet. Use the DefineSearch method to create an F1FindReplaceInfo object. The DefineSearch method sets up the search area and criteria. You may indicate the string you wish to find, the range of cells you wish to search within the worksheet, and any special flags you want to set such as matching case or matching the entire cell. The search itself is done by the FindNext method of the F1FindReplaceInfo object. The FindNext method returns True when it finds a matching string. It also sets the Row and Col properties for the F1FindReplaceInfo object so that they return the row and column in which the match was found. The Replace method of the F1FindReplaceInfo object replaces the search string found by the FindNext method with the replacement string of your choice.

96

Formula One ActiveX Users Guide

For more information regarding find and replace objects, properties, and methods, review the sections on the F1FindReplaceInfo object in the Formula One on-line help.

Inserting Cells, Rows, and Columns

You can insert cells, rows, or columns using the Workbook Designer or programmatically.

To insert cells using the Workbook Designer:

1. Select a range of cells in the size and place of the new cells that you want to insert. 2. Select Insert > Cells to display the Insert dialog box. 3. Select an Insert option button to specify a direction that you want the surrounding rows, columns, or cells to shift. 4. Click OK.

To insert rows using the Workbook Designer:

1. Select the same number of columns directly below where you want to add the new row or rows. 2. Select Insert > Rows.

To insert columns using the Workbook Designer:

1. Select the same number of columns directly to the right of where you want to add the new column or columns. 2. Select Insert > Columns.

To insert new cells programmatically:

s

Use the InsertRange method to insert new cells in a worksheet. You supply a range where new cells are inserted and specify how the current cells in that range should be shifted to make room for the new cells. The following example inserts a two by two block of cells starting at B2. The current cells in the range B2:C3 are shifted downward to make room for the new cells.
F1Book1.InsertRange 2, 2, 3, 3, F1ShiftVertical

Use the EditInsert method to insert cells, rows, and columns. You specify whether rows, columns, or cells should be inserted. This method call uses the currently selected range to determine how many rows, columns, or cells to insert.

When new cells are inserted, cell references in formulas are adjusted so the formulas remain correct.

Chapter 6 Editing Worksheets

97

The next four examples assume the range A4:B5 is selected (a two by two range). In the following code, data in all columns and rows 4 and below is shifted down two rows to allow room for the inserted cells.
F1Book1.EditInsert F1ShiftRows

The following code shifts all data in the worksheet right two columns to allow room for the inserted cells.
F1Book1.EditInsert F1ShiftCols

In the following code, data in all columns of rows 4 and 5 is shifted right two columns to allow room for the inserted cells
F1Book1.EditInsert F1ShiftHorizontal

In the following code, data in columns A and B in rows 4 and below is shifted down two rows to allow room for the inserted cells
F1Book1.EditInsert F1ShiftVertical

Clearing and Deleting Cells, Rows, and Columns

You can delete or clear cells, rows, or columns in the Workbook Designer or programmatically. Deleting cells removes the cells and shifts the surrounding data to fill the space. Clearing cells leaves the cells but deletes the data.

To delete cells in the Workbook Designer:

1. Select the cells, rows, or columns you want to delete. 2. Select Edit > Delete to display the Delete dialog box. 3. Select a Delete option button to specify a direction you want the surrounding rows, columns, or cells to shift. 4. Click OK.

To clear cells in the Workbook Designer:

1. Select the cells, rows, or columns you want to clear. 2. Choose one of the following, depending on what you want to clear from the cells: Select Edit > Clear > Contents to clear only the data and formulas. Select Edit > Clear > Formats to clear only the cell formats. Select Edit > Clear > All to clear the content and formats. 3. Click OK.

98

Formula One ActiveX Users Guide

To delete or clear cells programmatically:

Several methods delete and clear data. The following table lists these methods.
Method EditDelete DeleteRange EditClear ClearRange
s

Operation Deletes the current selection. Deletes the specified range. Clears the current selection. Clears the specified range.

EditDelete is similar to the EditInsert method. For EditDelete, you specify whether cells, rows, or columns should be deleted. The number of cells, rows, or columns deleted is determined from the current selection. For example, to delete rows (based on the current selection), you could use the following code:
F1Book1.EditDelete F1ShiftRows

If you delete cells (e.g., using EditDelete or DeleteRange) to which a formula refers, those formulas return a #REF! error because the referenced cells no longer exist.
s

To delete a specific range instead of the current selection, use the DeleteRange method. This method allows you to explicitly specify the range to delete. The following code uses this method.
F1Book1.DeleteRange 1, 1, 3, 3, F1ShiftRows

Clearing a cell can clear the value or format in a cell, or both. You can also specify whether or not formulas are cleared. Clearing does not shift other cells in the worksheet. The cleared cell has a value of zero. Formulas that refer to cleared cells obtain a value of zero from those cells.
s

You can use EditClear or ClearRange to clear a cell or range of cells. The following example clears the current selection.
F1Book1.EditClear F1ClearAll

Alternately, you can use the following example to clear specific rows or columns instead of the current selection.
F1Book1.ClearRange 1, 1, 3, 3, F1ClearAll

Sorting Data in Worksheets

You can sort the data in a worksheet and specify the keys by which the data is sorted. SortDlg displays a dialog box that allows the user to specify sort keys, sort rows or columns, and ascending or descending sort order. Before using the sort dialog box, a range in a worksheet must be selected. The data in the selected range is the data that is sorted. You can also sort worksheet data using the Sort or Sort3 methods. Refer to the Formula One Online Documentation for information about these methods.

Chapter 7 Formatting Worksheets

99

C H A P T E R

Formatting Worksheets

Formula One supports a rich set of data formatting capabilities. You can use number formats to display numbers in a certain way -- as dates, for example, or as dollars. You can use cell formats to change the size of cells and to add colors and borders. You can use font formats to change the typeface and style of the characters in your worksheet.

Using Built-in Number Formats

Number formats determine how numbers look when they appear in the worksheet. When you create a new worksheet, by default all cells in that worksheet use the General format, which means that as you enter data in the worksheet, Formula One determines the type of data and applies the appropriate number format (e.g., if you enter a date, a date format is applied). To specify formats other than General, you can apply a number of built-in number formats using the Workbook Designer. If you do not find the number format you want, you can create your own custom number format.

To apply number formats using the Workbook Designer:

1. Select the cells for which you want to change the number format. 2. Select Format > Cells and select the Number tab, if necessary. 3. Select a category for the number format from the Category list. 4. Type a number format or select a format type from the Type combo box. You can type a built-in format or a custom format. Refer to Creating Custom Number Formats on page 102 for more information about custom formats. 5. Click OK.

100

Formula One ActiveX Users Guide

The following table shows the built-in number formats for a US English locale and the result after the format is applied to a positive, negative, and decimal number.
Category and Format General Currency $#,##0_);($#,##0) $#,##0_);[Red]($#,##0) $#,##0.00_);($#,##0.00) $#,##0.00_);[Red]$(#,##0.00) _($* #,##0_);($* #,##0);_($* "-"_) ;_(@_) _($* #,##0.00_);($* #,##0.00);_($* "-"??_) ;_(@_) Fixed 0 0.00 #,##0 #,##0.00 #,##0_);(#,##0) #,##0_);[Red](#,##0) #,##0.00_);(#,##0.00) #,##0.00_);[Red](#,##0.00) _(* #,##0_);(* #,##0);_(* "-"_);_(@_) _(* #,##0.00_);(* #,##0.00);_(* "-"??_) ;_(@_) Percent 0% 0.00% Fraction # ?/? # ??/?? Scientific 0.00E+00 ##0.0E+0 $3 $3 $3.00 $3.00 ($3) ($3) in red ($3.00) ($3.00) in red ($ ($ 3) 3.00) -3 -3.00 -3 -3.00 (3) (3) in red (3.00) (3.00) in red ( ( 3) 3.00) -300% -300.00% -3 -3 -3.00E+00 -300.0E-2 $ $ $0 $0 $0.30 $0.30 3 3 -3 -3 .3 .3

$ $

3 3.00 3 3.00 3 3.00 3 3 3.00 3.00 3 3.00 300% 300.00% 3 3 3.00E+00 300.0E-2

0 0.30 0 0.30 0 0.30 0 0 0.30 0.30 0 0.30 30% 30.00% 2/7 3/10 3.00E-01 300.0E-3

Chapter 7 Formatting Worksheets

101

The following table shows the built-in date formats for a US English locale and the result after the format is applied to a date.
Format m/d/yy d-mmm-yy d-mmm mmm-yy m/d/yy h:mm 04/18/95 4/18/95 18-Apr-95 18-Apr Apr-95 4/18/95 0:00

The following table shows the built-in time formats for a US English locale and the result after the format is applied to a time.
Format h:mm AM/PM h:mm:ss AM/PM h:mm h:mm:ss m/d/yy h:mm mm:ss [h]:mm:ss mm:ss.0 12:02:02 12:02 PM 12:02:02 PM 12:02 PM 12:02:02 4/18/95 12:02 PM 02:02 12:02:02 02:02.0

Applying Number Formats to Rows and Columns

If you apply a number format to a row or column, that format is applied to all cells in the row or column. When you enter data in a cell in a formatted row or column, the data assumes the designated format. Formula One allocates memory by rows. Formatting empty rows or columns does not use memory. A format is merely attached to a row or column. Formatting empty ranges is treated differently. If you format a range of empty cells, a group of formatted, empty cells is created. Each new formatted, empty cell consumes memory. For more information about memory use in Formula One, see chapter 13, Performance Tuning and Specifications.

Obtaining Formatted Text Programmatically

You can obtain the formatted text in a cell by retrieving the value of the FormattedText, FormattedTextRC, or FormattedTextSRC properties. These properties return text exactly as it is displayed in the worksheet.

102

Formula One ActiveX Users Guide

Creating Custom Number Formats

In addition to the built-in number formats, you can define custom formats. Each custom format can have as many as four sections: one for positive numbers, one for negative numbers, one for zeros, and one for text. Each section is optional; the sections are separated by semicolons. The following example shows a custom format.
#,###;(#,###);0;"Error: Entry must be numeric"

To define a custom number format in the Workbook Designer:

1. Select the cells for which you want to create the custom number format. 2. Select Format > Cells and select the Number tab, if necessary. 3. Select a category for the custom number format from the Category list. 4. Type a custom number format built from the custom format characters described later in this chapter in the Type combo box. 5. Click OK.

To define a custom number format programmatically:

s

Use the NumberFormat property. The following code sets NumberFormat to format numbers in the current selection with two decimal places and negative numbers with parentheses.
Dim Fmt As F1CellFormat Set Fmt = F1Book1.CreateNewCellFormat Fmt.NumberFormat = #,##0.00_);(#,##0.00) F1Book1.SetCellFormat Fmt

Use FormatCellsDlg (F1NumberPage) to display the Format Cells dialog box. The Number tab of this dialog box allows you to select existing formats as well as define custom formats. The selected format is applied to all selections. The following code displays the Format Cells dialog box with the Number tab displayed.
F1Book1.FormatCellsDlg (F1NumberPage)

Chapter 7 Formatting Worksheets

103

The following table lists the format symbols that can be used in a custom format string.
Format Symbol General 0 Description Displays the number in General format. Digit placeholder. If the number contains fewer digits than the format contains placeholders, the number is padded with 0s. If there are more digits to the right of the decimal than there are placeholders, the decimal portion is rounded to the number of places specified by the placeholders. If there are more digits to the left of the decimal than there are placeholders, the extra digits are retained. Digit placeholder. This placeholder functions the same as the 0 placeholder except the number is not padded with 0s if the number contains fewer digits than the format contains placeholders. Digit placeholder. This placeholder functions the same as the 0 placeholder except that spaces are used to pad the digits. Decimal point. Determines how many digits (0s or #s) are displayed on either side of the decimal point. If the format contains only #s left of the decimal point, numbers less than 1 begin with a decimal point. If the format contains 0s left of the decimal point, numbers less than 1 begin with a 0 left of the decimal point. Displays the number as a percentage. The number is multiplied by 100 and the % character is appended. Thousands separator. If the format contains commas separated by #'s or 0's, the number is displayed with commas separating thousands. A comma following a placeholder scales the number by a thousand. For example, the format 0, scales the number by 1000 (e.g., 10,000 would be displayed as 10). Displays the number as scientific notation. If the format contains a scientific notation symbol to the left of a 0 or # placeholder, the number is displayed in scientific notation and an E or an e is added. The number of 0 and # placeholders to the right of the decimal determines the number of digits in the exponent. E- and e- place a minus sign by negative exponents. E+ and e+ place a minus sign by negative exponents and a plus sign by positive exponents. Displays that character. To display a character other than those listed, precede the character with a back slash (\) or enclose the character in double quotation marks (" "). You can also use the slash (/) for fraction formats. Displays the next character. The backslash is not displayed. You can also display a character or string of characters by surrounding the characters with double quotation marks (" "). The backslash is inserted automatically for the following characters: ! ^ & ` (left quote) ' (right quote) ~ { } = < > * (asterisk) Repeats the next character until the width of the column is filled. You cannot have more than one asterisk in each format section.

? . (period)

% , (comma)

E- E+ e- e+

$ - + / ( ) : space

104

Formula One ActiveX Users Guide

Format Symbol _ (underline) Description Skips the width of the next character. For example, to make negative numbers surrounded by parentheses align with positive numbers, you can include the format _) for positive numbers to skip the width of a parenthesis. Displays the text inside the quotation marks. Text placeholder. If there is text in the cell, the text replaces the @ format character. Month number. Displays the month as digits without leading zeros (e.g., 1-12). Can also represent minutes when used with h or hh formats. Month number. Displays the month as digits with leading zeros (e.g., 0112). Can also represent minutes when used with the h or hh formats. Month abbreviation. Displays the month as an abbreviation (e.g., JanDec). Month name. Displays the month as a full name (e.g., JanuaryDecember). Day number. Displays the day as digits with no leading zero (e.g., 1-2). Day number. Displays the day as digits with leading zeros (e.g., 01-02). Day abbreviation. Displays the day as an abbreviation (e.g., Sun-Sat). Day name. Displays the day as a full name (e.g., Sunday-Saturday). Year number. Displays the year as a two-digit number (e.g., 00-99). Year number. Displays the year as a four-digit number (e.g., 1900-2078). If you are using a Japanese locale, this displays the Latin letter for an era. If you are using a Japanese locale, this displays the first character of an era name. If you are using a Japanese locale, this displays the full era name. If you are using a Japanese locale, this displays the full era year. If you are using a Japanese locale, this displays the full era year with a leading 0 if the year is less than 10. Hour number. Displays the hour as a number without leading zeros (e.g., 0-23). If the format contains one of the AM or PM formats, the hour is based on a 12-hour clock. Otherwise, it is based on a 24-hour clock. Hour number. Displays the hour as a number with leading zeros (e.g., 0023). If the format contains one of the AM or PM formats, the hour is based on a 12-hour clock. Otherwise, it is based on a 24-hour clock. Minute number. Displays the minute as a number without leading zeros (e.g., 0-59). The m format must appear immediately after the h or hh symbol. Otherwise, it is interpreted as a month number. Minute number. Displays the minute as a number with leading zeros (e.g., 00-59). The mm format must appear immediately after the h or hh symbol. Otherwise, it is interpreted as a month number. Second number. Displays the second as a number without leading zeros (e.g., 0-59).

"text" @ m mm mmm mmmm d dd ddd dddd yy yyyy g gg ggg e ee h

hh

mm

Chapter 7 Formatting Worksheets

Format Symbol ss AM/PM am/pm A/P a/p [h] [m] [s] Description Second number. Displays the second as a number with leading zeros (e.g., 00-59).

105

12-hour time. Displays time using a 12-hour clock. Displays AM, am, A, or a for times between midnight and noon; displays PM, pm, P, or p for times from noon until midnight. Outputs total number of hours. Outputs total number of minutes. Outputs total number of seconds.

s.0, s.00, s.000, ss.0, Outputs fractional part of second. ss.00, ss.000 [Black] [Blue] [Cyan] [Green] [Magenta] [Red] [White] [Yellow] [Colorn] [conditional value] Displays cell text in black. Displays cell text in blue. Displays cell text in cyan. Displays cell text in green. Displays cell text in magenta. Displays cell text in red. Displays cell text in white. Displays cell text in yellow. Displays cell text using the corresponding color in the color palette. n is a color in the color palette. Each format can have as many as four sections: one each for positive numbers, negative numbers, zeros, and text. Using the conditional value brackets ([ ]), you can designate a different condition for each section. For example, you might want positive numbers displayed in black, negative numbers in red, and zeros in blue. The following string formats a number for these conditions:
[>0][Black]General; [<0][Red]General; [Blue]General

The following table shows some examples of custom number formats and numbers displayed using the custom formats.
Format
#.##

Cell Data 123.456 0.2 123.456 123 1234.567 0 -123.45

Display 123.46 .2 123.46 123.0 1,235CR 0 123DR 10

#.0#

#,##0"CR";#,##0"DR";0

#,

10000

106

Formula One ActiveX Users Guide

Format
"Sales="0.0

Cell Data 123.45 -123.45 -12.34 1234.567 -12.34 123456789 1234 Anything 123.45 -123.45 text

Display Sales=123.5 -Sales=123.5 x=-12.3 $ 1,234.57 $ -12.34 123-45-6789 Cust. No. 1234 (Not Displayed) The End -The End text 2-3-94 02 03 94 Feb 3, 94 February 3, 1994 3 February 1994 01h 32m 2.56 PM 0315 hours 1 1/4 1 2/8

"X="0.0;"x="-0.0 $* #,##0.00;$* -#,##0.00

000-00-0000 "Cust. No." 0000 ;;; "The End"

m-d-yy mm dd yy mmm d, yy mmmm d, yyyy d mmmm yyyy hh"h" mm"m" h.mm AM/PM hhmm "hours" #?/? #?/8

2/3/94 2/3/94 2/3/94 2/3/94 2/3/94 1:32 AM 14:56 3:15 1.25 1.25

Formatting Fonts
You may choose from many different fonts, font sizes, font styles, and font colors for any cells in your workbook. You can set a default font, font size, and style that will apply to all cells in all worksheets in the workbook. Later you can change these settings for individual cells. Changes you make to individual cells will remain, even if you change the default settings. For more information on changing the default font, see Setting the Default Font on page 46. Note By default, Formula One uses Arial as the default font. Be sure you always use a TrueType font as the default font in order for print and display scaling to work correctly.

Chapter 7 Formatting Worksheets

107

To set font formats for individual cells using the Workbook Designer:
1. Select the cells you wish to format. 2. Choose Format > Cells and click the Font tab, shown below.

A text sample with the font, style, and size you chose appears here. Some fonts provide scripts that allow you to use nonWestern alphabets. Choose the script you want here.

3. Select the font format settings you want, and click OK.

To set font formats for individual cells programmatically:

s

Use the SetFontEx method.

Aligning Data
Formula One allows you to specify how data is aligned within a cell. The standard alignment places text along the left edge of the cell and numbers along the right edge of the cell. Logical and error values are centered.

108

Formula One ActiveX Users Guide

To align text in the Workbook Designer:

1. Select the cells for which you want to align the contents. 2. Select Format > Cells and select the Alignment tab, shown below.

3. Specify the horizontal and vertical alignment of data in the selected cells using the Horizontal and Vertical lists. 4. Select the Wrap Text option to wrap long strings of data to multiple lines within the cell. 5. Click OK.

To align text programmatically:

s

Use the AlignHorizontal, AlignVertical, and WordWrap properties of the F1CellFormat object to set horizontal and vertical alignment and word wrapping for data in the selected cells. To align the text in the currently selected range(s), you can use the following code:
F1CellFormat.AlignHorizontal = F1HAlignCenter Centers the text horizontally F1CellFormat.AlignVertical = F1VAlignCenter Centers the text vertically F1CellFormat.WordWrap = FALSE Disables word wrapping

Use FormatCellsDlg with the Alignment tab displayed. The following code invokes the Format Cells dialog box with the Alignment tab displayed.
F1Book1.FormatCellsDlg (F1AlignmentPage)

Chapter 7 Formatting Worksheets

109

Merging Cells
You may merge two or more cells in order to create headings that span many columns or a column entries that span many rows. You can use merged cells to, for example, create a heading for several different columns of data, or to insert a block of text on a worksheet. You may merge cells in the Workbook Designer, or you may use properties and methods. When you merge cells, Formula One removes the cell borders between the merged cells and replaces any data in the cells with the data in the top left cell in the selection. To include all data in the range in the merged cell, copy all the data into the upperleftmost cell within the range before merging. Merged cells function as a single cell on the worksheet, with the row/column reference of the cell in the top-left corner of the range. For example, if you merge cells A1:B5, the resulting cell will have the cell reference A1.

To merge cells in the workbook designer:

1. Select the cells you want to merge. 2. Select Format > Cells and select the Alignment tab, shown on page 108. 3. Select the Merge Cells option. 4. Click OK.

To merge cells using properties and methods:

s

Use the MergeCells property of the F1CellFormat object.

Cutting, Copying, and Pasting Merged Cells

Merged cells behave a little differently than normal cells when it comes to cutting, copying, and pasting. Be aware of the following guidelines when you work with merged cells.

Pasting the entire merged cell range

Whenever you paste a range that contains merged cells, Formula One requires you to paste one or more copies of the entire range. It will not paste portions of the range containing the merged cell(s). This means that you must select a destination range (the range you are pasting into) that is:
s

equal to the number of rows and columns in the source range, or a multiple of the number of rows and columns in the source range, or a single cell.

110

Formula One ActiveX Users Guide

For example: A range two rows deep and two columns wide that contains merged cells can be pasted into a range four rows deep and two columns wide, or two rows deep and four columns wide. It cannot, however, be pasted into a range two rows deep and three columns wide.
Allowable ranges to paste merged cells into

Paste Special with merged cells

Some of the Paste Special command do not work when the source or destination of the paste is a range that contains merged cells. Specifically, you cannot use Paste Special to paste formulas or values to or from a range that contains merged cells.

Changing Row Height and Column Width

You can set the width of columns and the height of rows using menu commands, click and drag actions, or properties and methods. In addition, Formula One provides commands that allow you to define the default row height and default column width for your worksheet. Column and row sizing can be performed in the Workbook Designer at design time or in a workbook at runtime.

Setting Default Row Height and Width

Formula One provides menu commands that allow you to define the default row height and default column width for your entire worksheet. This section describes how to define these default settings.

Chapter 7 Formatting Worksheets

111

To define the default row height of a worksheet:

1. Select Format > Row > Default Height to display the Default Row Height dialog box which is shown in the following illustration.

For Formula One to automatically adjust the height of rows based on the values in cells, select the Auto option button.

2. Select the Custom option button define the default height of rows. 3. Enter a custom setting for the row height in the Custom text box. 4. Select whether the custom row height is entered as inches or centimeters from the Units drop-down list. 5. Click OK.

To define the default column width of a worksheet:

1. Select Format > Column > Default Width to display the Default Column Width dialog box which is shown in the following illustration.

Select Characters, Centimeters, or Inches for the unit in which the width is entered.

2. Enter a default width for columns and select a unit from the Units drop-down list. 3. Click OK.

Sizing Rows and Columns Using Menu Commands

You can set the width of selected columns and the height of selected rows using menu commands. This section describes the commands that allow you to perform these functions.

112

Formula One ActiveX Users Guide

To set the row height of a selection:

1. Select the rows for which you want to set the height. 2. Select Format > Row > Height to display the Row Height dialog box which is shown in the following illustration.
For Formula One to automatically adjust the height of rows based on the values in cells, select the Auto option button.

Click this button to display the Default Row Height dialog box.

To use the default settings, check this check box.

3. Select the Custom option button define a custom row height for the selected rows. 4. Enter a custom setting for the row height in the Custom text box. 5. Select whether the custom row height is entered as inches or centimeters from the Units drop-down list. 6. Click OK.

To set the column width of a selection:

1. Select Format > Column > Width to display the Column Width dialog box which is shown in the following illustration.

To use the default settings, check this check box.

Select Characters, Centimeters, or Inches for the unit in which the width is entered.

2. Enter a custom width for the selected columns and select a unit from the Units drop-down list. 3. Click OK.

Sizing Rows and Columns Using Click and Drag Actions

When you position the pointer on the right edge of a column heading or the bottom edge of a row heading, the pointer changes to a double arrow to indicate that the row or column can be resized. Simply click and drag to resize the column or row.

Chapter 7 Formatting Worksheets

113

If multiple rows are selected when you resize a row, all selected rows are resized as you drag a row border. Multiple columns can be resized in the same manner. Double-click the bottom border of a row heading to automatically adjust the height of all cells in the row to accommodate the largest font size in the row. Double-click the right side of a column heading to automatically adjust the width of all cells in the column to accommodate the largest entry. This is shown in the following illustration.
When the pointer appears, double-click this line to automatically size column A. Automatically sizing a column makes the cells wide enough for the longest text in the column.

When the pointer appears, double-click this line to automatically size row 1. Automatically sizing a row makes the cells tall enough for the largest text in the row.

You can also set the size of a selected group of columns or rows to match the size of an existing row or column. First, select the group of rows or columns you want to resize, including the row or column whose size you want to match. Then, click the right border of the column heading or the bottom border of the row whose size you want to match. The selected rows are resized to match the size of the row or column you clicked.

Note You can disable interactive sizing of rows and columns by setting the AllowResize property to False.

Sizing Rows and Columns with Properties and Methods

The following table lists the properties and methods that allow you to size rows and columns.
Property/Method ColHidden ColWidth Operation Sets or returns the display status of an individual column. Sets or returns the width of a single column in units of 1/256 of a average characters width in the default font or twips (1/1440th of an inch) depending on the setting of ColWidthUnits. Displays the Column Width dialog box. Sets or returns the width of the specified columns in twips.

ColWidthDlg ColWidthTwips

114

Formula One ActiveX Users Guide

Property/Method ColWidthUnits SetColWidth Operation Sets or returns whether column widths are stored and displayed in twips or character units. Sets the width of the specified columns in units of 1/256 of an average characters width in the default font or twips (1/1440th of an inch) depending on the setting of ColWidthUnits. Automatically sets the width of the specified columns to accommodate the largest data in the column. Changes the width of one or more columns to the specified number of twips. Sets or returns the height of a single row in twips. Sets or returns the display status of an individual row. Sets the height of the specified rows in twips (one twip equals 1/1440 inch). Automatically sets the height of the specified rows to accommodate the tallest data in the row. Displays the Row Height dialog box.

SetColWidthAuto SetColWidthTwips RowHeight RowHidden SetRowHeight SetRowHeightAuto RowHeightDlg

SetRowHeight and SetColWidth set the size of one or more rows or columns. For example, the following code sets the height of rows 1 through 10 to 1/2 inch, and the width of columns 1 through 10 (A through J) to 10 characters wide.
F1Book1.SetRowHeight 1, 10, 720, FALSE F1Book1.SetColWidth 1, 10, 2560, FALSE

SetColWidthAuto and SetRowHeightAuto automatically size rows and columns to accommodate the largest data in the row or column. For example, the following code automatically sets the row and column sizes of rows 1 through 10, and columns 1 through 10 (A through J).
F1Book1.SetRowHeightAuto 1, 1, 10, 10, TRUE F1Book1.SetColWidthAuto 1, 1, 10, 10, TRUE

Chapter 7 Formatting Worksheets

115

Freezing Horizontal and Vertical Panes

To scroll through your worksheet and see designated headings for columns or rows, split the worksheet into panes by freezing them. The following illustration shows a worksheet with frozen panes.
Columns A and B are frozen in this worksheet. When horizontal scrolling is performed, columns A and B do not scroll.

Before horizontal scrolling

After horizontal scrolling

Data contained in frozen panes cannot be edited. You must perform any data editing in these panes prior to freezing. If you attempt to select a cell in a frozen row or column, the entire row or column is selected, just as if you selected a row or column heading. This is shown in the following illustration.
Data in frozen rows and columns cannot be edited. When you attempt to select a cell in a frozen row or column, the entire row or column is selected.

To freeze horizontal panes in the Workbook Designer:

1. Select a cell in the row below where you want to split the panes. 2. Select Format > Freeze Panes. The rows above the split are frozen.

116

Formula One ActiveX Users Guide

To freeze vertical panes in the Workbook Designer:

1. Select a cell in the column to the right of where you want to split the panes. 2. Select Format > Freeze Panes. The columns to the left of the split are frozen.

To freeze panes using the Format Sheet dialog box in the Workbook Designer:
1. Select Format > Sheet > Properties and select the View tab. 2. Enter a range for the cells that you want to freeze in the Fixed Rows and Fixed Columns text boxes. For example, to freeze columns A - B and rows 1- 4 enter $1:$4 in the Fixed Rows text box and $A:$B in the Fixed Columns text box. 3. Click OK.

To freeze rows or columns programmatically:

s

Setting the FixedRow and FixedCol properties specify the starting row and column to freeze. The FixedRows and FixedCols properties determine how many rows or columns are frozen from the first row or column. The following example freezes A1:A4.
F1Book1.FixedRow = 1 F1Book1.FixedCol = 1 F1Book1.FixedCols = 1 F1Book1.FixedRows = 4

Setting Cell Border and Fill Formats

Cells and ranges can be formatted with borders of different outlines, line styles, and colors. In addition, cells and ranges can be formatted with colors and patterns. The following sections describe how to apply these attributes to cells.

Setting Cell Borders

Borders can be applied to the top, bottom, left, and right sides of a cell. When you add a border to a range, you can place a border around the outside of the range. You can set borders using the Workbook Designer or programmatically using properties and methods. To programmatically set formatting for cell borders, use the F1CellFormat API object.

Chapter 7 Formatting Worksheets

117

To format cells with borders using the Workbook Designer:

1. Select the cells you want to format. 2. Select Format > Cells and select the Border tab from the Format Cells dialog box. The following illustration shows an example of the Border tab.

Click a Line Style button to determine a line style for borders. Click a color to determine the color of the borders.

Click Automatic to assign the default color.

Click the buttons to specify on which sides of the cell or range the borders should appear.

Click directly on any of the areas in this box to toggle the display of borders.

These inside border buttons apply lines to any vertical or horizontal internal borders in the selected range. Inside borders are not available when only a single cell is selected.

Note You must select line style and color before selecting the location of the borders.
3. Select borders using the instructions in the previous illustration. 4. Click OK.

To format cell borders programmatically:

s

Use the F1CellFormat API object, BorderColor and BorderStyle properties, CreateNewCellFormat method, and the SetCellFormat method to create border styles for a cell or range.

The following example selects a range and places a thick light green border around the range.
Dim cellfrmt As F1CellFormat Set cellfrmt = F1Book6.CreateNewCellFormat thick border around the selection cellfrmt.BorderStyle(F1RightBorder) = F1BorderThick cellfrmt.BorderStyle(F1LeftBorder) = F1BorderThick cellfrmt.BorderStyle(F1TopBorder) = F1BorderThick cellfrmt.BorderStyle(F1BottomBorder) = F1BorderThick green border around the selection

118

Formula One ActiveX Users Guide

cellfrmt.BorderColor(F1RightBorder) = QBColor(10) cellfrmt.BorderColor(F1LeftBorder) = QBColor(10) cellfrmt.BorderColor(F1TopBorder) = QBColor(10) cellfrmt.BorderColor(F1BottomBorder) = QBColor(10) F1Book6.SetSelection 1, 1, 3, 3 F1Book6.SetCellFormat cellfrmt
s

Use FormatCellsDlg to invoke the Format Cells dialog box. The following code displays this dialog box with the Border tab displayed:
F1Book1.FormatCellsDlg (F1BorderPage)

Setting Cell Fill Colors and Patterns

When you apply colors and patterns to a cell or range, you specify the pattern and foreground and background colors used to fill the cells. These attributes can be set using the Workbook Designer or via code using properties and methods.

To format cells with colors and patterns using the Workbook Designer:
1. Select the cells you want to format. 2. Select Format > Cells and select the Patterns tab from the Format Cells dialog box. The following illustration shows an example of the Patterns tab.
Click Automatic to return to the default fill color and pattern color.

Click None to remove any fill pattern. A sample of the formatting is displayed in this area.

3. Click a fill color in the Fill Color palette to select it. 4. Click a pattern color in the Pattern Color palette to select it. 5. Click a pattern style in the Fill Pattern palette to select it. 6. Click OK.

To format cells with colors and patterns programmatically:

s

Use PatternBG, PatternFG, and PatternStyle properties of the F1CellFormat object to choose the background and foreground colors and pattern style for the selected cells.

Chapter 7 Formatting Worksheets

s

119

Use FormatCellsDlg to invoke the Format Cells dialog box. The following code displays this dialog box with the Patterns tab displayed:
F1Book1.FormatCellsDlg (F1PatternsPage)

Formatting Row and Column Headings

In addition to formatting worksheet cells, many aspects of row and column headings can be formatted. Worksheet headings contain three areas: the row headings, column headings, and the box in the top left corner of the worksheet where the row and column headings intersect. The following illustration highlights these three areas.
Column headings

Top left corner

Row headings

Selecting Row and Column Heading Areas

Row and column headings can be selected interactively or programmatically.

To select headings interactively:

s

Press CTRL+Shift and click the heading area.

To select a heading area programmatically:

s

Use SetHdrSelection. The following code selects the column heading area.
F1Book1.SetHdrSelection FALSE, FALSE, TRUE

Set the SelHdrRow, SelHdrCol, and SelHdrTopLeft properties to true. The following code selects the top left gray rectangle in the worksheet where the rows and columns intersect.
F1Book1.SelHdrTopLeft = TRUE

After a heading area is selected, you can set:

s

the alignment of the heading text

120

Formula One ActiveX Users Guide

s

the font and color of the heading text the pattern and fill color of the heading area the border used to frame heading cells

Sizing Row and Column Headings

The size of row, column, and top left headings can be set interactively and programmatically. The following illustration shows interactive resizing of the column headings.
A guide follows the pointer as you click and drag the heading border. The guide indicates the placement of the heading border when you When you resize column headings, you also set the height of the top left corner. Likewise, when you resize row headings, you set the width of the top left corner.

When the pointer is placed on an edge of the top left corner, it appears as a double arrow.

To interactively change the size of column headings:

s

Click and drag the bottom edge of the top left corner.

To interactively change the size of row headings:

s

Click and drag the right edge of the top left corner.

To change the size of column headings programmatically:

s

Use HdrHeight.

To change the size of row headings programmatically:

s

Use HdrWidth.

Setting Row and Column Heading Text

Like other column and row heading attributes, the text displayed in heading cells can be changed interactively or programmatically.

To interactively change the text for a row or column heading:

1. Double-click the heading for which you want to enter text to display the Header Name dialog box.

Chapter 7 Formatting Worksheets

121

2. Enter one or more lines of text to serve as the heading name. 3. Click OK. The heading text is displayed, as shown in the following illustration
When entering text in the Header Name dialog box, you can enter multi-line headings. Press RETURN to enter a line feed and start a new line.

The new text is displayed in the row heading. The row heading area has been resized to display the new heading text.

When you double-click a heading, the Header Name dialog box is displayed. Enter the heading text you want displayed in the dialog box.

You can control interactive editing of headings by setting the AllowEditHeaders property. You can return the value of AllowEditHeaders to determine whether interactively editing headings is allowed.

To set or return the text displayed in column headings programmatically:

s

Use ColText. Use RowText to set or return the text displayed in row headings. TopLeftText sets or returns the text displayed in the top left corner. With ColText and RowText, you must specify the column or row for which you are setting heading text. The following example sets the heading for column 4 to Orders instead of the default C.
F1Book1.ColText (3) = "Orders"

The following illustration shows the result of the example code.

The heading text for column C is replaced with "Orders" by the ColText property.

Note Rows, columns, and cells retain their default numbers and letters in functions, properties, and formulas even if the heading text for rows and columns is changed. For example, the cell at the intersection of column B and row 2 is still referred to as B2 even if the heading text for row 2 has been set to New Sales.

Tidestone

Chapter 8 Working With Graphical Objects

123

C H A P T E R

Working With Graphical Objects

Formula One provides the ability to create graphical objects in a worksheet. Among the graphical objects you can create are lines, rectangles, ovals, arcs, polygons, buttons, check boxes, dropdown list boxes, and charts. As with other worksheet elements, Formula One provides a wide range of options for formatting and manipulating the appearance of graphical objects you create. For specific information about creating and formatting charts, refer to Working With Chart Objects in this manual. Note Formula Ones graphical objects are incompatible with graphical objects in Microsoft Excel 95 and 97. You may still read and write Excel worksheets, but any graphical objects on those worksheets will not be transferred with the file. If you read or write an Excel file and save the file, any graphical objects that appeared in the original file will be lost.

Creating Graphical Objects

Formula One provides several methods for creating graphical objects in worksheets:
s

Graphical objects can be created by calling methods in your code. The Workbook Designer allows graphical objects to be created interactively. You can set the mode of the mouse to allow graphical objects to be created at any time.

The following sections describe each of these methods for creating graphical objects.

Creating Graphical Objects with Methods

Formula One provides several methods that allow you to create graphical objects from your application code.
s

Use ObjNew or ObjCreate to create lines, rectangles, ovals, arcs, buttons, check boxes, dropdown list boxes, and charts.

124

Formula One ActiveX Users Guide

s

Use OjbNewPicture or OjbCreatePicture to create a new metafile picture object on a worksheet.

The following example creates four adjoining arcs using the ObjCreate method:
Dim pid pid pid pid pid As Long = F1Book1.ObjCreate(F1ObjArc, = F1Book1.ObjCreate(F1ObjArc, = F1Book1.ObjCreate(F1ObjArc, = F1Book1.ObjCreate(F1ObjArc, 0.5, 2.5, 2.5, 4.5, 2, 2, 6, 6, 1.5, 1.5, 3.5, 3.5, 4) 4) 4) 4)

The following example creates four adjoining arcs using the ObjNew method:
Dim objID1 As Long Dim objID2 As Long Dim objID3 As Long Dim objID4 As Long F1Book1.ObjNew F1ObjArc, F1Book1.ObjNew F1ObjArc, F1Book1.ObjNew F1ObjArc, F1Book1.ObjNew F1ObjArc,

.5, 2, 1.5, 4, objID1 2.5, 2, 1.5, 4, objID2 2.5, 6, 3.5, 4, objID3 4.5, 6, 3.5, 4, objID4

The following illustration shows the result of the example code.

Interactively Drawing Graphical Objects

The Workbook Designer toolbar contains tools that allow you to interactively create and edit graphical objects. The following table describes the tools.
Button Name Polygon point editing tool Line tool Description Toggles between normal polygon editing and polygon point editing. When polygon point editing is enabled, use this tool to move the points of a polygon. Draws lines.

Rectangle tool

Draws rectangles and squares.

Oval tool

Draws ovals and circles.

Chapter 8 Working With Graphical Objects

Button Name Arc tool Description Draws arcs.

125

Polygon tool

Draws polygons.

Button tool

Draws buttons.

Check box tool

Draws check boxes.

Dropdown list box tool Draws dropdown list boxes. If Tidestones First Impression charting software is installed on your computer, this button accesses First Impression to create a chart based on the selected range of data.

Chart tool

Interactively drawing graphical objects in the Workbook Designer is as simple as point, click, and drag.

To create a graphical object in the Workbook Designer:

1. Click the tool for the graphical object you want to create. The pointer appears as a small cross when positioned in the worksheet. 2. Position the pointer at the point where you want to begin drawing. 3. Click and drag to create the graphical object. An outline of the graphical object you are creating appears and moves as you drag the mouse. 4. Release the mouse button to set the graphical object in place. Note When creating a graphical object, press ALT to align the graphical object to the cell grid.

Picture Objects
You can place a picture object on a worksheet and fill it with a metafile. Formula One provides two methods for doing this: one for drawing the picture object, and one for filling it with a metafile.

126

Formula One ActiveX Users Guide

s

Use ObjNewPicture or ObjCreatePicture to create a picture object on the current worksheet. You must specify the position for the new picture object. When specifying the location of the picture object, integers place the edge of the picture object on a row or column border; fractional numbers place the edge of the picture object between borders.

Use ObjSetPicture to place a metafile in an existing graphical object. You must provide a handle to the metafile and the ID number of the picture object into which you want the metafile placed. Any metafile previously contained by the picture object is freed from memory.

These methods also pass information about the dimensions of the picture and whether the picture can be stretched. Formula One manages the memory associated with a metafile once a picture object has been created, including freeing memory when the graphical object is deleted. You should be familiar with Windows metafiles and their structure before using these methods.

Setting Mouse Mode

By setting the mode for mouse actions, you can allow graphical objects to be drawn interactively in a worksheet.
s

Set the Mode property to change the mouse mode. You can specify that the mouse draw charts, lines, rectangles, ovals, arcs, buttons, polygons, check boxes, and dropdown list boxes. You can also specify that the mouse assume normal worksheet editing mode. Return the value of the Mode property to return the current mouse mode.

The following example uses Mode to set the mouse mode to rectangle drawing when you double-click a worksheet.
Private Sub F1Book1_DblClick(ByVal nRow As Long, ByVal nCol As Long) F1Book1.Mode = F1ModeRectangle End Sub

Identifying Graphical Objects

When you create a graphical object whether by method, in the Workbook Designer, or by setting the mouse mode the graphical object is assigned an identification number. Many methods or properties require a graphical object identification number to tell Formula One on which graphical object to operate. If you are uncertain of a graphical objects identification number, there are several ways to determine it.

Chapter 8 Working With Graphical Objects

127

To determine a graphical objects number in the Workbook Designer:

1. Select the graphical object for which you want to determine the identification number. 2. Select Format > Object to display the Format Object dialog box. 3. Select the Name tab. The Name tab displays the identification number of the selected graphical object, as shown in the following illustration.

The Name tab displays the identification number for the selected graphical object.

4. Click OK.

To determine a graphical objects number programmatically, use one of the

following properties or methods:
s

If a graphical object is selected, the ObjGetSelection method returns the identification number of the selected object. Formula One maintains a list of graphical objects in each worksheet within a workbook. The order of the graphical objects in that list is determined by the order in which graphical objects are drawn in the worksheet. The farther to the back a graphical object is placed or drawn, the higher the graphical object is placed in the list; the closer to the front a graphical object is placed or drawn, the lower the graphical object is placed in the list. Therefore, when you call ObjFirstID, this method returns the identification number of the first graphical object in the list, which is the graphical object created farthest back in the layers of worksheet graphical objects. Then, ObjNextID returns the identification number of the next closest graphical object, and so on.

Note When you use the ObjBringToFront and ObjSendToBack methods or the Bring To Front and Send To Back commands from the Format menu in the Workbook Designer, you alter the order of the graphical object list maintained by the worksheet.
s

If an graphical object has been named, you can return the identification number of the named graphical object with the ObjNameToID method.

128

Formula One ActiveX Users Guide

Naming Graphical Objects

As mentioned in the previous section, graphical objects can be named after they are created. Graphical object names do not take the place of graphical object identification numbers. Rather, graphical object names are used as a supplement to identification numbers, making it easier to track and manipulate graphical objects. Another purpose for naming graphical objects is to enable the ObjClick, ObjDblClick, ObjGotFocus, ObjLostFocus, and ObjValueChanged events. Before these events can fire, you must name the graphical object receiving the action. Graphical objects can be named in the Workbook Designer or programmatically.

To name a graphical object in the Worksheet Designer:

1. Select the graphical object you want to name. 2. Select Format > Object to display the Format Object dialog box. 3. Click the Name tab. 4. Enter the name to assign to the graphical object in the Name for Object text box.

To name a graphical object programmatically:

s

Set the ObjName property to name a graphical object. Once a graphical object is named, return the value of ObjName to obtain the name assigned to a graphical object. You can also call FormatObjectDlg (F1NamePage) to display the Format Object dialog box with the Name tab displayed.

Note After a graphical object is named, you must press CTRL to select it at runtime. In addition, if the ObjClick or ObjDblClick events are enabled, you must press CTRL when clicking the graphical object.

Selecting Graphical Objects

When working in the Workbook Designer or in a workbook at runtime, selecting graphical objects is an important first step when you are formatting, moving, or resizing graphical objects. In addition, many properties and methods such as SetPattern, SetLineStyle, ObjPatternStyle, ObjPatternFG, ObjPatternBG, ObjBringToFront, and ObjSendToBack require that a graphical object be selected for the property or method to work.

Chapter 8 Working With Graphical Objects

129

Interactively Selecting Graphical Objects

Selecting graphical objects interactively in the Workbook Designer or in a worksheet at runtime is as simple as pointing and clicking.

To interactively select a graphical object:

1. Position the pointer on the graphical object you want to select. The pointer appears as an arrow when positioned on a graphical object. 2. Click the graphical object. When the graphical object is selected, selection handles appear at the edges of the bounding box that surrounds the graphical object. Note For check boxes, dropdown list boxes, and buttons that have been named or if the ObjClick or ObjDblClick events are enabled, you must press CTRL when selecting the graphical object. In addition, in a worksheet at runtime, you must press CTRL to select arcs, lines, ovals, polygons, and rectangles that have been named. To select multiple graphical objects, press SHIFT as you select the graphical objects. For graphical objects that have been named, you must press CTRL+SHIFT to select multiple graphical objects. In the Workbook Designer, you can choose Edit > Select All Objects to select all the graphical objects in an active worksheet.

Limiting Interactive Graphical Object Selection

Setting the AllowObjSelections property allows you to specify whether users can interactively select graphical objects in the Workbook Designer or in a worksheet at runtime. Return the value of AllowObjSelections to determine if graphical object selections are allowed.

Selecting Graphical Objects Programmatically

To select graphical objects programatically, use one or more of the following:
s

ObjSetSelection selects the graphical object you specify by graphical object identification number. This method unselects any previously selected graphical objects or worksheet ranges. ObjGetSelection returns the identification number of the selected object. If more than one object is selected, you must indicate for which object to return an identification number. ObjAddSelection selects the specified graphical object; all previously selected objects remain selected.

130

Formula One ActiveX Users Guide

s

ObjSelection returns the identification number of the selected graphical object. If more than one graphical object is selected, you must indicate for which graphical object to return an identification number. ObjGetSelectionCount returns the number of graphical objects currently selected.

Moving, Sizing, and Arranging Graphical Objects

After a graphical object is created, you can change both the position and size of the graphical object. Formula One allows these changes to be made interactively or programmatically.

Interactively Moving and Sizing Graphical Objects

Interactively, graphical objects can be moved and resized at runtime or in the Workbook Designer.

To interactively move and size a graphical object:

1. Select the graphical object to be moved or sized. Note To select a named button, check box, or dropdown list box, you must press CTRL when selecting the graphical object. Or, if the ObjClick or ObjDblClick events are enabled, you must press CTRL when clicking the graphical object. When you select a graphical object, selection handles appear along the bounding box that surrounds the graphical object. 2. If moving the graphical object, position the pointer anywhere in the area occupied by the graphical object. If resizing the graphical object, position the pointer on one of the selection handles. When positioned in the graphical object area, the pointer appears as an arrow. When positioned on a selection handle, the pointer appears as a two-headed arrow, indicating the direction in which the graphical object can be resized. 3. Click and drag to move or resize the graphical object. An outline of the graphical object moves with the pointer as you drag the mouse. Note When moving or resizing a graphical object, you can align it to the worksheet grid by pressing ALT as you click and drag. 4. Release the mouse to set the graphical object at its new position or at its new size.

Chapter 8 Working With Graphical Objects

131

Positioning Graphical Objects Programmatically

Use the ObjSetPos method to set the position of a graphical object. Because the EndCol, EndRow, StartCol, and StartRow properties of the F1ObjPos API object and the ObjSetPos method set the placement of both anchor points of the bounding box that surrounds a graphical object, the graphical objects are also resized. If you are uncertain of an objects location, use the F1ObjPos API object or the ObjGetPos method to return the position of a graphical object. The following examples use ObjGetPos and F1ObjPos to obtain the position of the object. Then, ObjSetPos resizes the object by moving the second anchor point left one and a half columns and up five rows.
ObjGetPos Dim x1 As Dim y1 As Dim x2 As Dim y2 As and ObjSetPos Example: Single Single Single Single

F1Book1.ObjGetPos 1, x1, y1, x2, y2 F1Book1.ObjSetPos 1, x1, y1, (x2 - 1.5), (y2 - 5)

F1ObjPos and ObjSetPos Example:

Dim id As Long Dim F1ObjPos As Single Dim position As F1ObjPos id = F1Book1.ObjFirstID Set position = F1Book1.ObjGetPosEx(id) F1Book1.Text = position.startcol F1Book1.Text = position.startrow F1Book1.Text = position.endcol F1Book1.Text = position.endrow F1Book1.Text = position.Cols F1Book1.Text = position.Rows F1Book1.ObjSetPos id, position.startcol, position.startrow, (position.endcol - 1.5), (position.endrow - 5)

132

Formula One ActiveX Users Guide

The following illustration shows the results of these examples.

The first anchor point of the oval remains stationary.

Only the second anchor point is repositioned. Thus, the oval is resized.

You can also use the ObjPosShown method to return the graphical objects display status.

Determining Graphical Object Position and Size

The ObjPosToTwipsEx and ObjPosToTwips methods return the placement and size of a graphical object in twips. For these methods, you provide the position of a graphical objects anchor points in relation to the rows and columns of a worksheet. They also determine whether the graphical object is shown, partially shown, or hidden given the current dimensions of the view. These methods do not reference a specific graphical object on a worksheet and have no effect on any graphical objects.

Arranging Overlapping Graphical Objects

When you have multiple graphical objects on a worksheet, they appear to be drawn on the same plane. However, when two graphical objects overlap, the previously drawn object is covered by the latter-drawn object. You can change the order of graphical object layering in a worksheet by sending a graphical object behind other graphical objects or bringing a graphical object to the front of other graphical objects.

To arrange graphical objects in the Workbook Designer:

1. Select the graphical object you want to move. 2. Select Format > Bring to Front or Format > Send to Back to move the graphical object to the direction you specify.

To arrange graphical objects programmatically:

s

Call the methods ObjBringToFront or ObjSendToBack to arrange graphical objects. These methods move only the selected graphical objects.

Chapter 8 Working With Graphical Objects

133

If multiple graphical objects are selected when using these commands and methods, the order of graphical objects within the selection remains unchanged. The selected graphical objects are placed in front of or behind only the unselected graphical objects.

Arranging Graphical Object Order

When you use the ObjBringToFront and ObjSendToBack methods or the Format > Bring To Front and Format > Send To Back commands in the Workbook Designer, you alter the order of the graphical object list maintained by the worksheet. Refer to Identifying Graphical Objects on page 126 for information about how this affects the identification of graphical objects.

Formatting Graphical Objects

Many elements of graphical objects can be formatted including:
s

fill patterns and colors; line colors; and widths and styles for arcs, lines, ovals, polygons, and rectangles the lists of items contained by dropdown list boxes the text displayed by check boxes or buttons

Formatting Colors and Patterns

To set the fill colors and patterns for graphical objects arcs, ovals, polygons, and rectangles use the following methods:

To set fill colors and patterns for selected graphical objects in the Workbook
Designer: 1. Select the graphical object. 2. Select Format > Object to display the Format Object dialog box. 3. Select the Patterns tab. 4. Click a fill color in the Fill Color palette. This assigns a background color to the graphical object. 5. If you want to assign a pattern to the object, click a pattern style in the Fill Pattern palette, then click a pattern color in the Pattern Color palette. The pattern color will be the foreground color in the pattern. 6. Click OK.

To set fill colors and patterns for selected graphical object programmatically:
s

Use SetPattern to set the fill colors and pattern for the selected objects. Use ObjPatternStyle, ObjPatternBG, and ObjPatternFG to set the fill colors and pattern for the selected graphical objects.

134

Formula One ActiveX Users Guide

s

Call the FormatObjectDlg (F1PatternsPage) to display the Format Object dialog box with the Patterns tab displayed.

Formatting Lines (Borders) on Graphical Objects

To set the line style, color, and weight for line graphical objects and the lines that form the borders of arcs, ovals, polygons, and rectangles, use the following approaches.

To format lines for selected graphical objects in the Workbook Designer:

1. Select the graphical object. 2. Select Format > Object to display the Format Object dialog box. 3. Select the Line Style tab. 4. Click a line style or click None to not specify a line style. Line styles can be applied to line objects and the borders of arcs, ovals, polygons, and rectangles. The line styles are shown in the following illustration:
None Solid Dashed Ditted Dash-ditted Dash-dit-ditted

5. Click a line weight. Solid lines can be 1/2 point, 1 point, 2 points, or 3 points in weight. Styled lines can be 1/2 point in weight. The line weights are shown in the following illustration:
1/2 point (displayed as 1 point rule on low resolution monitors). 1 point 2 points 3 points

6. Click a color in the Color palette. This assigns a color to the line. 7. Click OK.

Chapter 8 Working With Graphical Objects

135

To format lines for selected graphical objects programmatically:

s

Use SetLineStyle to set the line style, color, and weight for the selected objects. Use the LineStyle, LineColor, and LineWeight properties to set the line style, color, and weight for the selected graphical objects. Call FormatObjectDlg (F1LineStylePage) to display the Format Object dialog box with the Line Style tab displayed.

Showing and Hiding Graphical Objects

A graphical object on a worksheet can be hidden by setting the ObjVisible property to False. To display a hidden graphical object, set the property to True. If you are uncertain whether a graphical object is shown or hidden, return the value of ObjVisible.

Formatting Dropdown List Boxes

Dropdown list boxes can be formatted by setting or changing the cell they reference, whether a selection appears in the referenced cell as a value or text, and specifying the list of selections in the dropdown list box.

To set or edit dropdown list box items in the Workbook Designer:

1. Create a dropdown list box, or select an existing one. When you draw the dropdown list box, draw an area wide enough to display the longest item in the list and as tall as the list of items you want to display. Formula One automatically sets the height of the list box; you set the height of the dropdown list of items. 2. Select Format > Object to display the Format Object dialog box. 3. Select the Options tab. The following illustration shows an example of the Options tab.

If you want the results of a selection to be displayed in a cell, type the cell location in the Cell text box.

Enter or edit the list of items contained by the dropdown list box. The items must be entered as a semicolon-delimited list.

Check the Assign As Text check box to assign the dropdown list box items as text, rather than values.

136

Formula One ActiveX Users Guide

4. Click OK. The following illustration shows the results.

When you select Marketing, the text for Marketing is displayed in the cell.

To set and manipulate the items contained in a dropdown list box

programmatically, use the following properties:
s

Set ObjItems to specify a list of items for a dropdown list box. For this property, you provide a semicolon-delimited list of items. The list you provide replaces any previously specified lists. Return the value of ObjItems to get a semicolondelimited list of items from a list box. To change an item in a list of items, set ObjItem. For this property, you provide the number of the item you want to change and the new value for the item. Return the value of ObjItem to get a specific item from a dropdown list box. To add an item to a list of items, use ObjAddItem. This method adds an item to the end of the current list. Use ObjInsertItem to add an item at a specific location within a list. Use ObjDeleteItem to delete an item from a dropdown list box. ObjGetItemCount returns the number of items contained by a dropdown list box. Use FormatObjectDlg (F1OptionsPage) to display the Format Object dialog box with the Options tab displayed.

Formatting Check Boxes

The text displayed by a check box can be set either through the Workbook Designer or programmatically.

To edit check box text in the Workbook Designer:

1. Select a check box. 2. Select Format > Object to display the Format Object dialog box. 3. Select the Options tab. 4. Edit the text displayed by the check box. 5. Click OK.

Chapter 8 Working With Graphical Objects

137

To set the text displayed in a check box programmatically:

s

Set the ObjText property. Return the value of ObjText to get the text displayed by a check box.

Formatting Buttons
The text displayed on a button can be set either through the Workbook Designer or programmatically.

To edit button text in the Workbook Designer:

1. Select a button. 2. Select Format > Object to display the Format Object dialog box. 3. Select the Options tab. 4. Edit the text displayed on the button. 5. Click OK.

To set the text displayed on a button programmatically:

s

Set the ObjText property. Return the value of ObjText to get the text displayed on a button.

Selecting Check Box and Dropdown List Box Items

Formula One provides a variety of methods for checking or unchecking check box objects and selecting items from dropdown list box objects.
s

At runtime, items can be checked or selected interactively using the mouse. Properties and methods can set the value of a check box or dropdown list box object. By assigning a cell to a graphical object, you can set the value in the cell by making a selection from the graphical object. Likewise, if you enter a value that is in the list associated with a dropdown list box, you can change the value displayed in the dropdown list box. The cell reflects the value to which the graphical object is set, regardless of the method used to set the value. When you check or uncheck a check box, or select an item from a dropdown list box, you set the value in the assigned cell.

For a check box, the value of the assigned cell is True if the graphical object is checked or False if unchecked. In a dropdown list box, you can choose to have the value of the assigned cell set to the number or the text of the selected item. Items in a dropdown list box are numbered starting with 0 (e.g., the first item is item 0, the second item is item 1, and so on). -1 means that no item is selected in the dropdown list box.

138

Formula One ActiveX Users Guide

Setting Values Interactively

To set the value of a check box or dropdown list box interactively, the graphical object itself cannot be selected and the pointer must be in normal worksheet editing mode.
s

To set the value of a check box, position the pointer anywhere in the check box area and click. The check box toggles between checked and unchecked states. To set the value of a dropdown list box, position the pointer anywhere in the dropdown list box area and click. The list of items contained by the dropdown list box is displayed. If the list area is not large enough to display all the items, you may have to click the scroll areas to view the entire list. Then, click the item you want to select.

Setting Values Programmatically

Set the ObjValue property to set the value of a check box or dropdown list box specified by graphical object ID number.
s

For check boxes, provide 1 to check a check box; provide 0 to uncheck the graphical object. For dropdown list boxes, provide the number of the item you want to select. Dropdown list box items are numbered consecutively, starting with 0. If you specify -1, no item is selected in the dropdown list box. Return the value of ObjValue to get the value of the current selection.

For dropdown list boxes, you can also use ObjText to set or return the text displayed on a button or next to a check box.

Setting Values by Cell Reference

For both check boxes and dropdown list boxes, you can specify a cell that references the graphical object. The referenced cell works in two ways:
s

If you select an item from the graphical object, the value or text of that selection is displayed in the referenced cell. For example, if you uncheck a check box, FALSE is placed in the cell the check box references. If you enter a valid value in the referenced cell, the current selection of the graphical object reflects the cell value. For example, if you enter 0 in the cell, a dropdown list box that references the cell displays its first item as the current selection.

If multiple graphical objects reference the same cell, making a selection in one graphical object makes the same selection in all graphical objects that reference the cell. The cell reference for a graphical object can be set in the Options tab of the Format Object dialog box.

Chapter 8 Working With Graphical Objects

139

To display or locate a cell reference interactively:

1. Select Format > Object to display the Format Object dialog box. 2. Select the Options tab. 3. If desired, type a cell reference in the Cell text box. 4. Click OK. You can also specify a cell reference by calling the ObjSetCell method. ObjGetCell returns an object cell reference. Furthermore, you can specify a cell reference by using the ObjCellType, ObjCellRow, and ObjCellCol properties. For dropdown list boxes only, you can specify whether the value or text of the selection is displayed in the cell.

Editing Polygons
When editing polygons, there are two editing modes:
s

Normal Polygon Editing. This mode allows you to resize and move polygons. Editing of polygon points is not allowed in this mode. Polygon Point Editing. This mode allows you to reposition polygon points, thus changing the shape of the polygon.

You can set the polygon editing mode by setting the PolyEditMode property. To determine the current polygon editing mode, return the value of PolyEditMode. In the Workbook Designer, to use normal polygon editing click the polygon and move the selection handles appropriately. If you want to use polygon point editing, click the polygon point editing tool and move the selection handles of the polygon. The following illustration shows a selected polygon when normal polygon editing and polygon point editing modes are enabled.
When normal polygon editing mode is enabled, the selection handles appear at the edges of the bounding box that surrounds the polygon. In this mode, the polygon can be resized and moved.

When polygon point editing mode is enabled, a selection handle appears at each point along the border of the polygon. In this mode, the polygon points can be repositioned and the polygon can be moved.

140

Formula One ActiveX Users Guide

To interactively reshape a polygon:

1. Select the polygon to be reshaped. 2. Make certain that polygon editing mode is enabled. When polygon editing mode is enabled, selection handles appear at each point along the border of the selected polygon. 3. Position the pointer on the polygon point that you want to move. 4. Click the point and drag the mouse. An outline of the lines adjoining the point move as you drag the polygon point. 5. Release the mouse button to place the point at its new location.

Chapter 9 Working With Chart Objects

141

C H A P T E R

Working With Chart Objects

If you have also purchased Tidestones First Impression ActiveX control, you can automatically chart worksheet data. In order to draw a chart, First Impression must be properly installed on your system. The following illustration shows an example of a chart on a worksheet.

This is the source range for the chart.

Creating Charts
To create a chart programmatically:
s

Use the ObjCreate with the F1ObjChart constant or the ObjNew method. These methods draw a chart object on the worksheet in the position you specify and chart the currently selected range. To change a charts data range, you must select it, open the Format Object dialog box, select the Options tab, and provide a range reference or defined name for the chart.

To interactively chart data:

1. Select a range of data to be charted. 2. Click the chart tool in the toolbar or select Insert > Chart.

142

Formula One ActiveX Users Guide

3. Using the chart tool, draw a rectangle where you want to place the chart. The Chart Wizard appears to assist you in designing the chart appearance. 4. Make any necessary selections from the Chart Wizard and click Finish.

Using the Chart Wizard

The pages within the Chart Wizard guide you through most common design decisions required when you create or modify a chart. The Chart Wizard is displayed automatically when you draw a new chart on a worksheet. You can also display the Chart Wizard at any time to assist you in formatting an existing chart. Important Each chart type has individual requirements as to how the data must be laid out. Separate formatting options are also available for different chart types. You should read your First Impression Users Guide to familiarize yourself with the requirements of various chart types.

To access the Chart Wizard:

1. Double-click on the chart to activate it. 2. Right-click the chart to display the context menu and select Wizard.

Navigating in the Chart Wizard

The Chart Wizard allows you to control various design aspects such as choosing a chart type, setting chart options, controlling chart layout, and specifying chart and axis titles. Use the navigation buttons at the bottom of the Wizard pages to navigate through the Chart Wizard.
Displays previous Wizard tab Applies modifications and closes the Wizard

Aborts changes and closes the Wizard

Displays next Wizard tab

Chapter 9 Working With Chart Objects

143

Using the Gallery Page

The Gallery Page allows you to select the type of chart you wish to design. Two radio buttons allow you to differentiate between 2D chart types and 3D chart types.

2D Charts

3D Charts

Using the Style Page

The Style Page lets you set the style for the selected chart type. Using the style page, you can easily set chart display options such as series labels, stacking, and bar gap.

Series Labels

Bar Gap

Series Stacking

144

Formula One ActiveX Users Guide

Using the Layout Page

The Layout Page provides methods for determining the elements and layout of the chart plot such as chart titles, chart footnotes, and chart legends.

Read data from grid columns

Using the Axes Page

The Axes Page allows you to optionally label chart axes. The chart preview image on this page shows you how the chart looks with your settings.

Important When you use the Chart Wizard to modify existing charts, the Wizard reverts the chart to its default settings and then restores only those features it controls in the Gallery, Layout, and Axes tabs. Exercise care when modifying charts that may have originally been created without the Wizard. You may need to manually adjust some chart settings after using the Wizard.

Chapter 9 Working With Chart Objects

145

The Chart Wizard provides a quick and easy method for applying some of the most common formatting options to your chart. Additional formatting options are available by using the First Impression Chart Designer. The Chart Designer is displayed by double-clicking on chart elements in an activated chart object, or selecting Chart Designer from the First Impression context menu. You can modify chart data by selecting Edit Chart Data from the First Impression context menu. The Data Grid Editor will appear. Consult your First Impression documentation for more information about the Chart Designer, the Data Grid Editor, and other First Impression functions.

To access First Impression functions:

1. Double-click on the chart object to activate it. 2. Right-click on the chart to display the context menu. 3. Make a selection from the menu.

Double-click to activate the chart for formatting.

Right-click on the chart to display the First Impression context menu.

Important One of the options on the First Impression context menu is Edit Chart Data. This displays First Impressions Data Grid Editor. Using this tool you can modify the size and content of the charts data source. Any changes you make in the Data Grid Editor are reflected in the chart, but are NOT reflected in the worksheet. Also, if you use the Data Grid Editor to edit the chart data and then recalculate the workbook in Formula One while the chart still references a range in

146

Formula One ActiveX Users Guide

the worksheet, the worksheet data overwrites your changes. To prevent this, select the chart, choose Format > Object, and replace the charts formula with an empty string (" ") before using the Data Grid Editor to edit the data.

Chart Options
Within Formula One, you can control whether or not users can edit the chart and change the source data range for a chart using the Options tab of the Format Object dialog box.

To edit chart options:

1. Select the chart. 2. Choose Format > Object to display the Format Object dialog box. 3. Select the Options tab.

Unselect this option to prevent users from formatting the chart. Formula identifying the source data range for the chart.

Developers Note If you make the Workbook Designer available to your end users, they will have access to the Allow User Changes check box. To prevent them from modifying a chart regardless of this setting, set the AllowObjSelections property to False.

Chapter 9 Working With Chart Objects

147

Referencing Data on Another Worksheet

You can also display a chart on one worksheet that references data on a separate worksheet.

To create a chart on a separate worksheet:

1. Select the chart. 2. Choose Format > Object to display the Format Object dialog box. 3. Select the Options tab. 4. Enter the formula referencing the data source on the other spreadsheet.

This worksheet provides summary information about the inventory data stored on the worksheets named Region 1 and Region 2. These cells contain formulas that sum information from the worksheets individual region.

The data source formula for this chart object is Summary!B3:D17

Tidestone

Chapter 10 Printing Worksheets

149

C H A P T E R

1 0

Printing Worksheets

Formula One provides many options for printing worksheets and setting printing specifications.
s

You can print worksheets through the Workbook Designer. You can use properties and methods of the F1PageSetup object to print worksheets directly. See the Formula One online documentation for more information on the F1PageSetup object and its properties. You can also use methods to display the Page Setup and Printer Setup dialog boxes.

Printing Worksheets
You can print the active worksheet from the Workbook Designer, or from code.

To print the active sheet from the Workbook Designer:

1. Select File > Print to display the Print dialog box. 2. You may preview the printout by pressing the Preview button. Formula One will display the Print Preview dialog, shown on page 159. 3. Make any necessary adjustments to the settings and click OK.

To print the active sheet from code:

s

Use the FilePrint method. The following code uses this method to print a worksheet.
F1Book1.FilePrint TRUE

When you call FilePrint, the Print dialog box can be displayed, allowing you to specify the pages to print, the number of copies to print, and other related items.
s

Use FilePageSetupDlgEx to display the Page Setup dialog box, which gives easy access to setting margins, headers, footers, headings, grid printing, page ordering, and output alignment. The following code displays the Page Setup dialog box.
F1Book1.FilePageSetupDlgEx

150

Formula One ActiveX Users Guide

To print selected sheets or the entire workbook from code:

s

Use the FilePrintEx method. The following code uses this method to print selected worksheets or the entire workbook as a single document.
F1Book1.FilePrintEx bShowPrintDlg, bPrintWorkbook

When you call FilePrintEx, the Print dialog box can be displayed, allowing you to specify the pages to print, the number of copies to print, and other related items.
The Print dialog default printing selection can be changed by setting the appropriate flag in the FilePrintEx method.

Use FilePrintSetupDlg to invoke the Print Setup dialog box; the standard Windows printer setup dialog box is displayed. It allows you to select a printer, select the paper source, and select the page orientation (portrait or landscape). The following code displays the Print Setup dialog box.
F1Book1.FilePrintSetupDlg

Specifying Print Areas

Formula One prints the entire active worksheet unless you specify the ranges you want to print. To specify the areas you want to print, you must set the Print_Area name to reflect the worksheet area to be printed.

To set the print area with menu commands in the Workbook Designer:
1. Select the ranges to print. 2. Select File > Print Area > Set Print Area.

Chapter 10 Printing Worksheets

151

To set the print area using the Page Setup dialog box in the Workbook Designer:
1. Select File > Page Setup and click the Sheet tab. The Sheet tab of the Page Setup dialog box will appear, as shown below.

If a print area was already set, the range(s) will appear here.

2. In the Print Area text box, enter the range(s) on the selected worksheet(s) that you want to print. You may enter absolute or relative cell references. Separate noncontiguous ranges with commas. When you finish, click OK.

To set the print area in code:

s

Use the PrintArea and PrintAreaLocal properties of the F1PageSetup object.

The following example uses the PrintArea property to set A1:D25 as the area to be printed.
Dim pgSetup As F1PageSetup Set pgSetup = F1Book1.CreateNewPageSetup pgSetup.PrintArea = "A1:D25" F1Book1.SetPageSetup pgSetup

You can select multiple ranges to print. The ranges do not have to be adjacent. For example, a print area could be comprised of two ranges, A1:D4 and F5:I8.

Specifying Print Titles

You can specify row or column titles that you want printed on each page of your worksheet. If you select a row, it is printed at the top of each page. If you select a column, it is printed at the left edge of each page. You can select multiple rows or columns, but they must be adjacent. Important When setting print titles, you must select entire rows and columns.

152

Formula One ActiveX Users Guide

To set the print titles with menu commands in the Workbook Designer:
1. Select the rows or columns to use as print titles. You must select entire rows or columns. 2. Select File > Print Titles > Set Print Titles.

To set the print titles using the Page Setup dialog box in the Workbook
Designer: 1. Select File > Page Setup and click the Sheet tab. The Sheet tab of the Page Setup dialog box will appear, as shown on page 151. 2. In the Print Titles text box, enter the row and/or column range(s) on the selected worksheet(s) that you want to appear on every page of the printout. You may enter absolute or relative cell references. Separate non-contiguous ranges with commas. When you finish, click OK.

To set the print titles in code:

s

Set the PrintTitles or PrintTitlesLocal property of the F1PageSetup object.

The following example uses the PrintTitles property to set rows 1 and 2 and column A as print titles.
Dim pgSetup As F1PageSetup Set pgSetup = F1Book1.CreateNewPageSetup pgSetup.PrintTitles = "A1:IV2,A1:A65536" F1Book1.SetPageSetup pgSetup

Specifying Page Breaks

Both horizontal and vertical page breaks can be specified on a worksheet. You can specify page breaks interactively using the Workbook Designer, or you can use methods and properties. In the Workbook Designer, page breaks are always placed adjacent to the active cell. When using methods, page breaks can be placed adjacent to the active cell or a cell that you specify.
s

For horizontal (row) page breaks, the page break will be placed above the active or specified cell. For vertical (column) page breaks, the page break will be placed to the left of the active or specified cell.

To set page breaks in the Workbook Designer:

1. Select the cell adjacent to which you want to place page breaks. 2. Select Insert > Page Break.

Chapter 10 Printing Worksheets

153

To remove page breaks in the Workbook Designer:

1. To remove a horizontal page break, select a cell in the row below the break. To remove a vertical page break, select a cell in the column to the right of the break. 2. Select Insert > Remove Page Break.

To set and remove page breaks in code:

There are several categories of page break methods. The AddPageBreak and RemovePageBreak methods add page breaks adjacent to the active cell. The following example uses these methods:
F1Book1.AddPageBreak F1Book1.RemovePageBreak

AddRowPageBreak, AddColPageBreak, RemoveRowPageBreak, and RemoveColPageBreak add and remove page breaks adjacent to the row or column that you specify in the method. The following example uses the AddRowPageBreak method:
Dim theRow As Long theRow = 8 F1Book1.AddRowPageBreak theRow

NextRowPageBreak returns the next page break below the row that you specify in the method. NextColPageBreak returns the next page break to the right of the column that you specify in the method. The following example uses the NextRowPageBreak method:
Dim nextBreak As Long Dim theRow As Long theRow = 20 nextBreak = F1Book1.NextRowPageBreak (therow)

154

Formula One ActiveX Users Guide

Specifying Margins
You may set margins in inches or centimeters, or you may tell Formula One to use whatever margins it takes to print the print area in the center of the worksheet. You may also establish margins for headers and footers.

To specify margins in the Workbook Designer:

1. Choose File > Page Setup. Click on the Margins tab. The Margins tab of the Page Setup dialog box appears, as shown below.

Click here to center the page between the left and right margins. Click here to center the page between the top and bottom margins.

Use these boxes to enter the distance between the edge of the page and the header or footer. If the header or footer margin is larger than the top or bottom margin, the header or footer will overwrite the worksheet data on the page.

2. Select the options you want. Click OK when you are done.

To specify margins programmatically:

s

Use the following properties of the F1PageSetup object: TopMargin, LeftMargin, BottomMargin, RightMargin, HeaderMargin, FooterMargin, CenterHoriz, and CenterVert.

Chapter 10 Printing Worksheets

155

Setting Page Numbering

You may number the worksheet pages automatically starting at 1 or at any number you choose. Note By default, the page numbers you set here appear on the worksheet footer. To change the location of the page number on the printout, change the worksheet footer and/or header.

To specify page numbering in the Workbook Designer:

1. Choose File > Page Setup. Click on the Page tab. The Page tab of the Page Setup dialog box appears, as shown below.

To scale the worksheet in order to make it fit on a certain number of pages, click the Fit to button, then enter the number of pages tall and wide in these dialog boxes.

If you dont want page numbering to start at 1, enter the first page number here.

Choose Automatic to start numbering pages at 1 (if this is the first or only worksheet in the print job) or at the next sequential number (if this is not the first worksheet in the print job).

2. Select the options you want. Click OK when you are done.

To specify page numbering programmatically:

s

Use the AutoPageNumber and FirstPageNumber properties of the F1PageSetup object.

156

Formula One ActiveX Users Guide

Specifying Headers and Footers

Headers are printed at the top of each page and footers are printed at the bottom. You can define the alignment, contents, and formatting of headers and footers.

To specify headers and footers in the Workbook Designer:

1. Choose File > Page Setup. Click the Header/Footer tab. The Header/Footer tab of the Page Setup dialog box appears, as shown below.

2. Type text and special formatting codes in the Header and Footer boxes. See below for information on special formatting codes. When you finish, click OK.

To specify headers and footers programmatically:

s

Use the Footer and Header properties of the F1PageSetup object.

Formatting Codes for Headers and Footers

Header and footer codes allow you to format and align the text and to insert worksheet-specific information, like page numbers and the worksheet name. The alignment codes (&L, &C, and &R) must go before font-related codes (like &B for bold and &I for italic). Codes for printing worksheet-specific information like worksheet title go last. If you put the codes in the wrong order, Formula One may ignore some of them. Enter codes in upper or lower case and separate them with a space. By default, codes and text are centered unless &L or &R is specified.
Format Code &L &C &R &B Description Left-aligns the characters that follow. Centers the characters that follow. Right-aligns the characters that follow. Use a bold font.

Chapter 10 Printing Worksheets

Format Code &I &U &S &O &H &"fontname" &nn &D &T &F &A &P &P+number &P-number && &N Description Use an italic font. Underline the header. Strikeout the header. Ignored. Ignored. Use the specified font. Use the specified font size (must be a two-digit number) Prints the current date. Prints the current time. Prints the workbook name. Prints the worksheet name. Prints the page number. Prints the page number plus number. Prints the page number minus number. Prints an ampersand. Prints the total number of pages in the document.

157

Setting Page Orientation

You may print pages in portrait or landscape orientation.

To specify page orientation in the Workbook Designer:

1. Choose File > Page Setup. Click the Page tab. The Page tab will appear, as shown on page 155. 2. Choose Portrait or Landscape, then click OK.

To specify page orientation programmatically:

s

Use the Landscape property of the F1PageSetup object. If you do not set this property, landscape printing can be handled using your systems default Print dialog box.

Setting Up Scaling for Printing

You may specify a specific scale percentage to print your chart. You can also force the chart to print on a specified number of pages.

To specify worksheet size and scale in the Workbook Designer:

1. Choose File > Page Setup and click the Page tab. The Page tab will appear, as shown on page 155. 2. To specify a scale factor, enter it in the Adjust To text box.

158

Formula One ActiveX Users Guide

3. To force the chart to fit on a specified number of pages, click the Fit to button, then enter the number of pages tall and pages wide you want the worksheet to fit into. 4. When you finish choosing options, click OK.

To specify worksheet size and scale programmatically:

s

Use the PrintScale, FitPages, PagesWide, and PagesTall properties of the F1PageSetup object.

Specifying Page Printing Order

You may use the Page Setup dialog box to specify the order in which to print your worksheet pages, or you may specify page order programmatically.

To specify page order in the Workbook Designer:

1. Choose File > Page Setup and click the Sheet tab. The Sheet tab will appear, as shown on page 151. 2. To print from the top to bottom margins, click Top to Bottom. The data in the leftmost columns prints before the data in columns farther out. 3. To print from the left to right margins, click Left to Right. The data in the uppermost rows prints before the data in lower rows. 4. Click OK.

To specify page order programmatically:

s

Use the LeftToRight property of the F1PageSetup object.

Choosing Paper Size

To specify paper size in the Workbook Designer:
1. Choose File > Page Setup and click the Page tab. The Page tab will appear, as shown on page 155. 2. Choose the paper size from the dropdown list box, then click OK.

To specify paper size programmatically:

s

Use the PaperSize property of the F1PageSetup object.

Specifying Miscellaneous Printing Options

Formula One lets you choose whether or not you want certain worksheet page elements to appear on the printout and whether you want your printout in color or black and white.

Chapter 10 Printing Worksheets

159

To specify miscellaneous printing options in the Workbook Designer:

1. Choose File > Page Setup and click the Sheet tab. The Sheet tab will appear, as shown on page 151. 2. Check the Grid Lines box if you want grid lines to appear on the printout. 3. Check the Black & White box if you want any colored elements on the worksheet to be printed in shades of gray. 4. Check the Row Heading and Column Heading boxes to make row and column headings appear on the printout. 5. Click OK when you are done.

To specify miscellaneous printing options programmatically:

s

Use the BlackAndWhite, GridLines, RowHeadings, and ColHeadings properties.

Previewing Your Printout

Formula One lets you preview the pages that are going to print. You can preview the printout of your worksheet(s) from the Workbook Designer, or you can use properties and methods.

To preview your printout in the Workbook Designer:

1. Choose File > Print Preview. The Print Preview screen appears, as shown below.

If your printout has multiple pages, you can use the Next Page and Prev Page buttons to view the different pages.

160

Formula One ActiveX Users Guide

s

An image of what the printout will look like appears on the screen, showing the margins, headers and footers, print titles, page breaks, and other printing features discussed in this chapter. When you finish, click Close. To print the worksheet(s) directly from this screen, click Print. Formula One prints all pages as shown, without showing you the Print dialog box, and closes Print Preview.

To preview your printout using properties and methods:

Formula One provides a three methods to simplify adding print preview functionality to your application. As a developer, you can set the PrintPreviewEx method to preview worksheets prior to printing. This method allows a device context to be passed for painting the sheet. With PrintPreviewEx a window handle and a rectangle are passed in, along with the page number to display. The PrintPreviewEx method allows VB programmers and others to add print preview functionality. A simpler method of previewing worksheets utilizes the FilePrintPreview method. By calling the FilePrintPreview method, you can display a dialog that previews the printed page. For MFC users, the PrintPreviewDCEx method can be used with the print preview mechanism provided by MFC. The PrintPreviewDCEx method allows a device context to be passed in for painting the sheet. A page number is also passed in and the total number of pages in the sheet is passed back to the user.

Chapter 11 Working With Databases

161

C H A P T E R

1 1

Working With Databases

Database connectivity is one of Formula Ones most powerful features. You can use Formula One, along with ODBC drivers, to retrieve data from a database and use it to populate a Formula One worksheet at the starting row and column position you specify. This ODBC connection offers incredible speed and flexibility in populating your worksheet.

Overview of Formula One Connections

Database connections are made on a per worksheet basis. This means that you can populate each worksheet in a workbook with data from a different query, or even a different database. This is a powerful feature because Formula One worksheet functions work across multiple worksheets. As an example, you can query district sales information, and place information from each district in a separate worksheet within the same workbook. On each worksheet, you can perform summary calculations to show statistics for that district. You can also add additional worksheets to the workbook that execute summaries or analysis on any combination of the districts. If you also purchase Tidestones First Impression charting tool, you can select a range of data in a worksheet and draw a chart illustrating that data on the Formula One worksheet.

Installing the ODBC Drivers

In order to connect a Formula One worksheet to a database via ODBC, you must have the 32-bit version of the ODBC drivers installed on your system. These drivers come with most 32-bit development environments such as Visual Basic 4.0, Office95, and Visual C++ 2.x. When you install these environments be sure to select the ODBC option. If you have already installed your development environment, you can re-install and check only the ODBC option. Be aware that different environments offer different drivers. Please contact your development environment vender for information about the drivers available.

162

Formula One ActiveX Users Guide

Setting up a Data Source

You can create a new data source from within Formula One, or you might find it more convenient to set up your data sources outside of Formula One.

To set up a data source outside of Formula One:

1. Double-click the ODBC icon in the Control Panel to bring up the Data Sources dialog box. 2. Click Add to add a connection to the database you want to reach. 3. In the Add Data Source dialog box, choose the appropriate 32-bit driver for the database you are connecting to and click Finish. This brings up an ODBC dialog box based on the driver you chose. 4. Enter a Data Source Name and Database Name that describe the database you want to connect to and click OK.

Connecting to the Data Source

Formula One provides the F1ODBCConnect API object used with the ODBCConnectEx method to connect the active worksheet to a database. In addition, Formula One provides the ODBCConnect method to connect the active worksheet to a database. If you are using the ODBCConnectEx method to connect the active worksheet to a data source, you provide ODBC connection with the following:
s

a connect object (F1ODBCConnect). a boolean that controls whether SQL errors are displayed. The following code example shows the use of this object and method:
If Command1 = True Then Dim pConnect As New F1ODBCConnect Dim F1obdcconnect As String pConnect.ConnectStr = F1ODBCConnect F1Book1.ODBCConnectEx pConnect, True connecterror: MsgBox Error

To allow the user to select the database at runtime, the F1ODBCConnect object should be equal to a null string.

Chapter 11 Working With Databases

163

If you are using the ODBCConnect method to connect the active worksheet to a data source, you provide ODBC connection with the following:
s

a variable containing a connect string. a boolean that controls whether SQL errors are displayed. a variable that receives the returned SQL status code. The following code example shows the use of this method:
On Error GoTo ConnectError Dim returnCode As Integer, pConnect As String F1Book1.ODBCConnect pConnect, True, returnCode Exit Sub ConnectError: MsgBox Error

The connect string must be a variable. This allows you to let the user select the database at runtime and returns the data source in the connect string. Next, a dialog box is displayed, allowing the user to select or create a file data source or machine data source at runtime. The following illustration shows the File Data Source tab of the Select Data Source dialog box

This selection describes the driver for which you want to connect. You can use any file data source that refers to an ODBC driver on your machine.

Click New to create a new data source.

If you want to create a new data source, click New. This launches the ODBC Datasource Administrator Utility for your database. For more information, consult your database administrator documentation. For more information about ODBCConnect or ODBCConnectEx, refer to the Formula One online documentation.

164

Formula One ActiveX Users Guide

Querying the Data Source

Once you connect to a data source, you can build and execute a query. This is accomplished using Formula Ones F1ODBCQuery API object and ODBCQueryEx method or the ODBCQuery method. If you are using ODBCQueryEx, you must provide the following information:
s

an ODBC query object. if the query string is null, the ODBC Query dialog box is displayed to allow the user to build the query at runtime. row and column coordinates that identify where in the active worksheet the returned data is to be placed. a boolean that determines whether the ODBC Query dialog box is displayed. variables that control whether data and data type information is used to format the worksheet size, column headings, column width, and cell formatting. a variable that received the returned status code.

Below is the code that implements this in the demo.

On Error GoTo FetchError Dim pConnect As New F1ODBCConnect Dim pQuery As New F1ODBCQuery Dim bShowDlg As Boolean connect to SouthCreek database pConnect.ConnectStr = "DSN=SouthCreek" F1Book1.ODBCConnectEx pConnect, True prompt for query at runtime initially , query Is Empty Cell format, column names, column width, and the maximum number of rows and columns displayed is determine from the data that is retrieved from the database pQuery.SetColFormats = True pQuery.SetColNames = True pQuery.SetColWidths = True pQuery.SetMaxRC = True pQuery.QueryStr = "" bShowDlg = True F1Book1.ODBCQueryEx pQuery, 1, 1, bShowDlg Exit Sub FetchError: MsgBox Error

Chapter 11 Working With Databases

165

If you are using ODBCQuery, you must provide the following information:
s

a variable that specifies the query syntax. If you pass a null string for this argument, the ODBCQuery dialog box is displayed to allow the user to build the query at runtime. The query string must be passed as a variable. This allows you to let the user build the query at runtime and returns the final query string. row and column coordinates that identify where in the active worksheet the returned data is to be placed. a boolean that determines whether the ODBCQuery dialog box is displayed. variables that control whether data and data type information is used to format the worksheet size, column headings, column width, and cell formatting. a variable that received the returned status code.

Below is the code that implements this in the demo:

On Error GoTo FetchError Dim returnCode As Integer, query As String Dim setColNames As Boolean, setColFormats As Boolean Dim setColWidths As Boolean, setMaxRC As Boolean Let query = cboQueries.TEXT setColNames = chkSetColNames.Value setColFormats = chkSetColFormats.Value setColWidths = chkSetColWidths.Value setMaxRC = chkSetMaxRC.Value F1Book1.ODBCQuery query, Val(txtStartRow.TEXT), Val(txtStartCol.TEXT), optShowDialog.Value, setColNames, setColFormats, setColWidths, setMaxRC, returnCode Exit Sub FetchError: MsgBox Error

166

Formula One ActiveX Users Guide

If the query string is null or you set the bShowDialog value to True, the query dialog is displayed as shown in the following illustration.

Connection Information

Use these Table and Fields lists to assist you in building your query.

Type the SQL syntax for your query in this text box.

Set Column Widths. Check this box to automatically set the width of each column to be wide enough to display the widest data in the column. Set Column Names. Check this box to display field names instead of the standard alphabetic column headings. Even though field names are displayed as the column headings, formulas must still use the standard cell referencing conventions (e.g., A1). Set Column Formats. Check this box to have formats for date, time, and currency fields set automatically when data is placed in the worksheet. If you do not check this box, you must set the formats for these columns manually. Set MaxRow & MaxCol. Check this box to have the maximum number of worksheet rows and columns set to the number of records and fields returned by the query.

Chapter 11 Working With Databases

167

When you click OK in the ODBC Query dialog box, the query is executed. The following example shows the results of a returned query.

Notice that Set Column Names and Set MaxRow and Max Column have been set to True. Column labels have been replaced with database field names and the size of the worksheet has been adjusted to the number of returned columns and rows.

Note To maintain Excel compatibility, each cell is limited to 256 characters. If the returned data exceeds this limit, the text is truncated to fit in the cell

Updating or Inserting Data

Formula One supports the use of prepared SQL statements to update database data, or insert or delete database records. Following is an overview of this process:
s

Establish a database connection using ODBCConnectEx or ODBCConnect. Build a PREPARE statement using ODBCPrepareEx or ODBCPrepare. If necessary, bind the PREPARE statement parameters to worksheet columns using one or more ODBCBindParameterEx or ODBCBindParameter methods. Execute the PREPARE statement with ODBCExecuteEx or ODBCExecute.

In addition, Formula One provides tools for handling errors that occur during this process:
s

ODBCError. ODBCError can be checked after failure of any Formula One ODBC method. ODBCErrorMsg. The ODBCErrorMsg property returns a detailed message of the error that occurred. ODBCNativeError. The ODBCNativeError property displays ODBC native error information to the user following an ODBC method failure.

168

Formula One ActiveX Users Guide

s

ODBCExecuteError. The ODBCExecuteError event allows you to determine what happens if an error is encountered during the execution of the prepared statement. ODBCSQLState. The ODBCSQLState property shows an SQL state error number after failure of any Formula One ODBC method.

A common way you might want to incorporate these features into a Formula One application is to populate a worksheet with database data using ODBCQueryEx or ODBCQuery which allows the user to edit the information, and then update the database with the user updates. You can use the EndEdit event to determine if the user has made changes, or the SelChanged event to determine when a user leaves a particular row.

Using PREPARE Statements

ODBCPrepareEx or ODBCPrepare sends an SQL string to the database via ODBC. For specific information about creating PREPARE statements, refer to your SQL documentation. The string sent by ODBCPrepareEx or ODBCPrepare can be any valid SQL statement. Formula One does not attempt to parse or modify the statement before sending it to SQLPrepare. ODBCPrepareEx or ODBCPrepare are specifically designed to provide you a way to perform UPDATE, INSERT, and DELETE operations from within your Formula One code. It is NOT recommended that you use ODBCPrepareEx or ODBCPrepare to send SELECT statements from the database in order to populate a worksheet with data. ODBCQueryEx or ODBCPrepare are optimized to retrieve data from a database and display it in worksheet columns more efficiently. A PREPARE statement can contain static or dynamic information. You would use static parameters when you have a single, well-defined change to make to the database. The following code for ODBCPrepareEx adds a new record to the Product table.
retcode = F1Book1.ODBCPrepareEx ("INSERT INTO Product (id,name,description,size,color,quantity,unit_price) VALUES (701,Sunglasses,wrap-around,Medium,Black,80,75)")

The following code for ODBCPrepare adds a new record to the Product table.
F1Book1.ODBCPrepare "INSERT INTO Product (id,name,description,size,color,quantity,unit_price)", "VALUES (701,Sunglasses,wrap-around,Medium,Black,80,75)", retCode

However, when working with worksheets, you more commonly want to supply data from the worksheet as a parameter in your PREPARE statement. For example, if you have a number of new authors listed in a worksheet and you want to add them all to your database you could use variable parameters to make your PREPARE statement more dynamic. In this way you can supply data from the worksheet as the statement is executed.

Chapter 11 Working With Databases

169

The following code for ODBCPrepareEx allows the user to supply data to the worksheet as the statement is executed:
retcode = F1Book1.ODBCPrepareEx ("INSERT INTO Product SET (id = ?, name = ?, description = ?, size = ?, color = ?, quantity = ?, unit_price = ?)")

The following code for ODBCPrepare allows the user to supply data to the worksheet as the statement is executed:
F1Book1.ODBCPrepare "INSERT INTO Product SET id = ?, name = ?, description = ?, size = ?, color = ?, quantity = ?, unit_price = ?", retCode

In this case, each of the question marks is a variable parameter tag that must be bound to a worksheet column using the ODBCBindParameterEx.

Binding Worksheet Columns

When you use variable parameter tags in an ODBCPrepareEx or ODBCPrepare statement, you must bind each parameter to a column in the worksheet and identify the type of data that is located in that worksheet column. If the ODBCPrepareEx or ODBCPrepare statement contains two variable parameter tags, it must be followed by two separate ODBCBindParameterEx or ODBCBindParameter statements. The following example uses ODBCBindParameter to creates a PREPARE statement and binds parameters in the PREPARE statement to columns in the illustrated worksheet.

The following examples binds these columns. F1Book1.ODBCPrepare "INSERT INTO Product SET id = ?, name = ?, description = ?, size = ?, color = ?, quantity = ?, unit_price = ?", retCode

Binds the first question mark to the second worksheet column and specifies that the data type as Long.
F1Book1.ODBCBindParameter 1, 2, F1CDataLong, retcode

170

Formula One ActiveX Users Guide

Binds the second question mark to the second worksheet column and specifies the data type as Character.
F1Book1.ODBCBindParameter 2, 2, F1CDataChar, retcode

If you do not provide a bind for each question mark in the PREPARE statement, the ODBCExecute or ODBCExecuteEx statements fail. Formula One does no checking to verify that the data in the column matches the type you have specified. If there is a data conversion error during an ODBCExecuteEx or an ODBCExecute, the ODBCExecuteError event is fired. ODBCExecuteError allows you to trap for data conversion errors and determine a course of action. The error handler also returns the affected row and column in the worksheet so that you can determine which cell is causing the problem.

Executing PREPARE Statements

Once you create a PREPARE statement and bind any variable parameters to worksheet columns, you are ready to execute the PREPARE statement. ODBCExecuteEx and ODBCExecute use any information provided in ODBCBindParameterEx or ODBCBindParameter statements to fill in the variables in the ODBCPrepareEx or ODBCPrepare statement. They then attempt to execute the PREPARE statement. If you are filling in parameters with worksheet data, the ODBCExecuteEx or ODBCExecute methods also identify which worksheet rows to process. Important If any Formula One ODBC statement other than ODBCError, ODBCSQLState, ODBCNativeError, ODBCErrorMsg, ODBCBindParameterEx, or ODBCBindParameter are placed between ODBCPrepareEx or ODBCPrepare and ODBCExecuteEx or ODBCExecute, the PREPARE string you were attempting to build is lost and the execute fails. The following example for ODBCExecute processes the bound data in the first 11 rows of the spreadsheet through the PREPARE statement.
F1Book1.ODBCExecute 1, 11, retCode

If an error occurs during an ODBCExecuteEx or ODBCExecute, an ODBCError, ODBCSQLState, ODBCNativeError, or ODBCErrorMsg is executed. You can provide code to determine what happens when an error is encountered.

Disconnecting from the Data Source

After your query you should disconnect from the database. This is done with the ODBCDisconnect method. Following is a code example showing the use of this method.
F1Book1.ODBCDisconnect

Chapter 12 Using Formula One With the Internet

171

C H A P T E R

1 2

Using Formula One With the Internet

Using Formula One, you can save an entire worksheet in HTML format for use on the Internet, or embed a Formula One worksheet in an existing HTML file. You can write only the HTML data or pass the full design capabilities of the Workbook Designer to your HTML document. Formula One can also be used by containers for Internet and corporate Intranet application development. The Formula One 5.0 ActiveX workbook control has been digitally signed by Verisign Commercial Software Publishers CA and supports the to IObjectSafety interface for secure data. There are a number of tools available to assist you in creating the necessary files for displaying the Formula One ActiveX workbook control on your web page. For an up-to-date list of tools and instructions on how to obtain them, visit our website at http://www.tidestone.com/internet.

Writing out a Worksheet File in HTML Format

Formula One users can save a worksheet in HTML format using the File > Write command. The Write dialog box gives them the option of saving the document as:
s

HTML. HTML format including data formatting, font and color information. HTML (Data Only). HTML format includes data formats, but excludes font and color information.

To write a document to HTML programmatically:

s

Use the SaveFileDlg or SaveFileDlgEx method to call the Write dialog box. The following example uses SaveFileDlgEx to call the Write dialog box. The default file type is set to HTML.
Dim pFileInfo As New F1FileSpec pFileInfo.Name = F1Book1.Title pFileInfo.Type = F1FileHTML F1Book1.SaveFileDlgEx "Save As HTML", pFileInfo

172

Formula One ActiveX Users Guide

Embedding Formula One Data in an HTML file

To embed a Formula One worksheet in an existing HTML file:
1. Create a Formula One project and write some code utilizing the InsertHTML method to embed the worksheet into an HTML file. 2. Create an anchor point (location) in the HTML file where you want the worksheet embedded.

Utilizing the InsertHTML Method

The most important aspect of the InsertHTML method is declaring an AnchorName variable. AnchorName identifies the location in your HTML file where you wish to insert your Formula One worksheet. The following example declares AnchorName = data1 and inserts a worksheet into the HTML document titled mortgage.
Private Sub Command1_Click() Dim nRow1 As Long Dim nCol1 As Long Dim nRow2 As Long Dim nCol2 As Long Dim nSheet As Long Dim pAnchorName As String pAnchorName = "data1" nRow1 = 1 nCol1 = 1 nRow2 = 10 nCol2 = 5 nSheet = 1 F1Book1.InsertHTML nRow1, nCol1, nRow2, nCol2, nSheet, App.Path & "\mortgage.HTML", True, pAnchorName End Sub

Creating an Anchor in your HTML Source File

Depending on the HTML editor you are using, the technique used to create an anchor or target location in your HTML document might vary. Consult your HTML editor documentation for details on how to edit HTML files. The following example shows the HTML markup code for an anchor and anchor description data1.
<CENTER><P><A NAME="data1"></A></P></CENTER>

Chapter 12 Using Formula One With the Internet

173

HTML Document Design

The final HTML document design depends on the limitations of your HTML editor and your own creative ability. Formula One allows you to pass the full design capabilities of the Workbook Designer to your HTML document through the Write method and the HTML file type. When writing a worksheet file, you can save your file as a number of file types. By choosing the HTML file type, you ensure that any worksheet design characteristics such as font, text alignment, and color are passed to your HTML document. If you choose to write your file as an HTML (Data only) file type, you save text without any design attributes.

Introducing Internet Application Development

Formula One can be used by containers for Internet and corporate Intranet application development. The Formula One ActiveX workbook control has been digitally signed by Verisign Commercial Software Publishers CA and supports the to IObjectSafety interface for secure data.

Viewing a Web Page Containing Formula One

When a browser encounters a web page containing an ActiveX control, a unique exchange of information must take place between the browser and the web server before the ActiveX control is rendered on the page. First, the Browser program checks to see if a copy of the ActiveX control resides on the clients computer. If not, the browser extracts the Formula One ActiveX control (and any dependent files) from the Cabinet file that resides on the server and copy them to the client machine. Next, the browser program parses a License Pack File on the server in order to validate the license that was embedded in the Formula One control at design time. The browser then passes the extracted license key to the Formula One control on the client machine. If the license key from the .LPK file matches the Formula One controls license, the control is rendered on the web page.

174

Formula One ActiveX Users Guide

Adding Formula One to your Web Page

In order to successfully add Formula One to your web page you must completing the following tasks: 1. Create an HTML web page that contains the Formula One ActiveX control. 2. Create a License Pack File to use for registering the control on the browser machine. 3. Create an .INF File that lists all of the controls dependencies. 4. Create a Cabinet File to compress and store the files needed for downloading by the browser program. 5. Copy the License Pack and Cabinet Files to your Internet Server where they can be accessed by the browser program. For specific instructions on how to create these files, visit our website at http://www.tidestone.com/internet.

Using Methods and Events for Internet Development

Some containers (such as Microsofts Internet Explorer) cannot use ByRef parameters. Formula One provides alternatives to the ByRef methods and events currently offered in the API. Refer to your Formula One on-line help for more information about the methods and events that are available as alternatives for Internet development.

Understanding Formula Ones IObjectSafety Support

Formula One supports the IObjectSafety interface for Internet application development. The IObjectSafety interface allows a control to instruct a container that it is safe for initialization or scripting. On an Internet download, the browser can request that the control enter safe mode. When this request is detected, the following methods are disabled so they do not harm the users system:
Draw FilePrintPreview ObjCreatePicture ODBCBind Parameter ODBCConnectEx ODBCErrorMsg ODBCNativeError ODBCQuery OpenFileDlg PrintPreview PrintPreviewEx FilePrint GetTabbedText ObjNewPicture ODBCBindParameterEx ODBCDisconnect ODBCExecute ODBCPrepare ODBCQueryEx OpenFileDlgEx PrintPreviewDC Read FilePrintEx InsertHTML ObjSetPicture ODBCConnect ODBCError ODBCExecuteEx ODBCPrepareEx ODBCSQLState PrintDevMode PrintPreviewDCEx ReadEx

Chapter 12 Using Formula One With the Internet

ReadFromBlob Write WriteRangeEx SaveFileDlg WriteEx WriteToBlob SafeFileDlgEx WriteRange WriteToBlobEx

175

The following worksheet functions are also disabled in your browser when the safe request is detected:
CALL REGISTER.ID

Note If you want to load a workbook from an Internet address, use the URL property. For additional information about this property, refer to the Formula One Online Documentation.

Understanding Formula Ones Safe Events

Formula One provides alternative events that are safe for use on the Internet. These events are only fired if you set the DoSafeEvents property to True. The following table includes a list of the events that are replaced with their safe counterparts.
Events Internet Alternative Events

BeforeReplace Found EndEdit ODBCExecuteError StartEdit ValidationFailed

SafeBeforeReplace SafeFound SafeEndEdit SafeODBCExecuteError SafeStartEdit SafeValidationFailed

Tidestone

Chapter 13 Performance Tuning and Specifications

177

C H A P T E R

1 3

Performance Tuning and Specifications

Using Performance Tuning

The following tips can help you make the most efficient use of memory and get the best performance from Formula One.
s

Avoid formatting blank cells. It is more efficient to format an entire row or column because no cells are created. When you format a blank range that does not consist of whole rows or whole columns, Formula One must create empty cells before it can apply the format. To find and eliminate blank formatted cells in your worksheet, show cell markers by using the ShowTypeMarkers property. (You can do this in the Workbook Designer by choosing Tools > Options, clicking the General tab, and checking the Show Markers box.) With markers turned on, Formula One will display a blue frame inside blank, formatted cells. Build worksheets by rows instead of columns. Formula One allocates memory by rows. You can save memory by building tables a row at a time, rather than a column at a time. For example, fill cells in row 1 before moving to row 2, and so on, rather than filling cells in column A before moving to column B, and so on. Build ranges from the lower right corner. When building a table one cell at a time from code, it is faster and more efficient to start in the lower right corner of the area in which you are working. This ensures that the row pointers are allocated simultaneously instead of one at a time. Likewise, each row is allocated once instead of being reallocated as each cell is added. Use values instead of formulas whenever possible. Avoid adding empty rows and columns for white space. Adjust the row height or column width to create white space instead of adding empty rows or columns. If you must have additional white space on your worksheet, empty rows are more efficient than empty columns. Disable repainting when performing a series of operations. When performing a number of sequential operations on a worksheet, disable repainting with the Repaint property so the screen does not repaint after each operation. This increases the speed of the operation and avoids unnecessary screen flashing.

178

Formula One ActiveX Users Guide

s

Use methods to copy and move data. Use EditCopyRight, EditCopyDown, CopyRange, CopyRangeEx, and MoveRange to copy and move cells. These methods are much faster than using the clipboard. In addition, these methods update cell references to maintain the integrity of your formulas.

Optimizing Formula One

Formula One allocates an array of row pointers for each row that has data. For each row, it then allocates an array of column pointers. Rows that do not have data in them only have a row pointer allocated for that row and not an array of column pointers for that row. Therefore, it is better to fill the sheet by rows instead of columns when possible. Since the row and column pointers are allocated based upon the last row or column with data in them, it is best to load the sheet from the bottom-right up to the top-left. This allows Formula One to allocate the entire array of row and column pointers before it fills the sheet. With these arrays pre-allocated then it only has to allocate space for each cell depending on the cell size. If the Formula One sheet is not loaded from the bottom-right to the top-left, then the arrays of row and column pointers must grow as the number of rows and columns grow. Each time these arrays need to grow, it must find a contiguous block of memory to hold the entire array. This leads to disk swapping and decreased speed. If it is not possible to load the sheet from the bottom-right, then another way to preallocate the arrays is to put a value in the bottom-right hand corner of the sheet. This will pre-allocate the row pointers. In order to pre-allocate all the arrays of column pointers, the entire column on the right would need to be loaded with a value. This would be recommended if the number of columns is large. After the data has been loaded into the sheet, then the cell at the bottom-right can be deleted. The sheet will then re-evaluate the amount of memory that it needs and give back the rest. This will speed up load times considerably.

Understanding Formula Ones Data Structure

There are three basic parts to a Formula One data structure: the row pointers, the cell pointers, and the cells. Formula Ones data structure starts with a set of row pointers. This row pointer array is a contiguous block of memory containing one 4-byte pointer for each row. For example, if you have a spreadsheet that contains 10 rows, the row pointer array contains 10 pointers of 4 bytes each. As you add rows, this array expands. Each row that is not blank consists of an array of cell pointers large enough to point to the last cell in a row. The cell pointer array is a contiguous block of memory containing one 4-byte pointer for each cell. So, if the last cell in a row is located in column H (the eighth column), that row contains eight 4 byte pointers (for columns A through H).

Chapter 13 Performance Tuning and Specifications

179

Finally, there are the cells themselves, which are small data structures containing the cells contents. The structures include a cells value, its format, its formula, its font, its alignment, and other cell attributes. Cells only exist in memory if they contain formulas or data or are formatted differently from the row or column in which they are located.

Allocating and Freeing Memory

Generally speaking, it is an expensive operation to get memory from and return memory to Windows (referred to as allocating and freeing memory). Every time a spreadsheet has to obtain a new chunk of memory, time is consumed. Additionally, allocating chunks of memory in varying sizes tends to fragment the memory pool. At some point, you may need to obtain a piece of memory that is a certain size, and find that it does not exist, although there is plenty of free memory scattered throughout your system in small pieces.

Filling Worksheets with Data

Consider the case of filling a 1,000 row by 10 column spreadsheet with a set of values or formulas. If you start from the top left corner, the first cell you create causes the row pointer array to allocate one pointer to the first row. Then, the first cell pointer is allocated in row 1. And finally, the first cell (A1) is allocated. When you fill cell B1, the cell pointer array in row 1 increases to two pointers and cell B1 is created. This continues until all 10 cells in row one are created. If you are keeping score, you will note that Formula One performed 21 memory allocations: one for the row pointer, 10 for the cell pointers, and 10 for the cells themselves. This operation can be optimized by filling the row from right to left. This causes the cell pointer array to be allocated once, eliminating 9 memory allocations (and the associated memory copying and freeing operations). Continuing with the spreadsheet filling, row 1 is completed and you are ready to fill row 2. Before you start filling the row, the row pointer array is expanded to 2 pointers (one for each row). Then, row 2 is created just like row 1. Remember, our sample spreadsheet contains 1,000 rows. So, the row pointer array is expanded 1,000 times. This is unnecessary and very time consuming. By the time you reach the onethousandth row, Formula One is looking for a block of memory 4,000 bytes long (since there is 4 bytes allocated for each row pointer). This part of the operation can be optimized by filling the rows from bottom to top. This causes the row pointer array to be allocated once instead of 1,000 times. Employing these two simple optimizations reduces the number of memory allocations from 21,000 (for 1,000 row pointers, 10,000 cell pointers, and 10,000 cells) to 11,001 (1 row pointer, 1,000 cell pointers, and 10,000 cells). But reducing the number of memory allocations is only half the story.

180

Formula One ActiveX Users Guide

When you expand the row pointer array or a cell pointer array, Formula One must ask for a larger piece of memory, copy the contents of the current array into the new memory array, and then return the previous memory block to the memory pool. The 9,999 memory operations you eliminated are the most expensive operations. How can this be? The secret is that the optimized method for filling the worksheet avoided dealing with fragmented memory, as happened with the slow method. As the cell pointer arrays grew larger, the remaining chunks of free memory were not big enough for the growing arrays. This caused Windows to start paging memory to disk to produce large enough memory chunks. You can achieve the same results without actually filling a worksheet from bottom to top. When you start filling data, make sure the maximum-needed row pointer array is allocated by entering a cell in the last row you are going to use. This forces a row pointer array to be created that will accommodate your entire worksheet. Then, it doesnt matter what row you fill next because this array will not change. Likewise, if you always create the last cell in any row first, the maximum-needed cell pointer array is created. Then, you can enter the cells in that row in any order without affecting performance.

Using Technical Specifications

The following table lists the technical specifications for the Formula One control.
Specifications Maximum worksheet size Column width Row height Text length Formula length Number precision Largest positive number Largest negative number Smallest positive number Smallest negative number Maximum number of iterations Maximum number of colors Maximum number of available colors Maximum number of fonts per workbook Maximum number of selected ranges Maximum number of names per workbook Maximum length of name Maximum number of function arguments 65,536 rows by 256 columns 0 to 255 characters 0 to 409 points 16,383 characters 1024 characters 15 digits 9.99999999999999E307 -9.99999999999999E307 1E-307 -1E-307 32,767 56 Limited by display card and monitor 256 2048 Limited by available memory 255 30

Chapter 13 Performance Tuning and Specifications

Specifications Maximum length of format string Maximum number of tables (workbooks) Excel file format version 255

181

Limited by system resources (windows and memory) Excel 5.0, 95, and 97

Tidestone

Chapter 14 Creating Add-In Functions

183

C H A P T E R

1 4

Creating Add-In Functions

This chapter provides information about add-in functionssmall programs that extend the capabilities of Formula One. The examples presented here demonstrate how to extend Formula Ones functions by adding the capability to use array arguments in functions using Visual Basic and C++.

Formula One ActiveX Add-Ins in Visual Basic

General Design Principles
Formula One implements Add-Ins as ActiveX DLLs. To function as a Formula One Add-In, an ActiveX DLL must, at a minimum, implement a creatable class named F1Functions. When the DLL is registered with Formula One either through the API or through the Add-In Manager dialog, Formula One attempts to locate and create this class. Formula One only recognizes the DLL as a valid add-in if the DLL implements a creatable F1Functions class. Note In Visual Basic, the standard way to make a class creatable in an ActiveX DLL is to set the classs Instancing property to a value of 5. Visual Basic describes such a class as MultiUse. Formula One treats any member of the F1Functions class that follows the guidelines set forth in this chapter as a worksheet function and ignores any functions not meeting the guidelines. All arguments must also be passed ByVal. Note ByVal means by value. When a parameter is passed by value, anyone referencing that parameter is prevented from modifying that variables value.

184

Formula One ActiveX Users Guide

As Formula Ones add-in capabilities increase, future versions may look for new classes in addition to F1Functions. To maximize compatibility with future versions of Formula One, add-in developers should refrain from using the prefix F1 on internal class names in their add-in DLLsespecially on classes that are creatable. Formula One presents the ActiveX DLLs project description to end-users via the Add-In Manager dialog; therefore, the project description should be an informative phrase (typically no longer than a short sentence) describing the addin DLL. The Project Description field can be found on Visual Basics Project Properties dialog under the General page.

Thread Safety
Although Formula One is single-threaded, future versions of Formula One may support multithreading. If so, Formula Ones calc engine will create a separate instance of F1Functions for each thread. This means that if your add-in functions use only automatic variables or data defined within the F1Functions class, you will not need to be concerned about thread safety. However, if you must refer to data outside of F1Functions (for example, if all threads must share common data), you are responsible for ensuring that your code is thread-safe.

Add-In Function Requirements

All arguments to an add-in function must be passed ByVal or the function will not be recognized by Formula One. To use the F1AddInArray and F1AddInArrayEx types, the Formula One control must be added to the project. Formula One recognizes functions that use the following data types (all arguments must be ByVal):
Allowed as Return Value Yes Yes No No Yes Yes Allowed as Argument Yes Yes Yes Yes Yes Yes

Type Boolean Double F1AddInArray F1AddInArrayEx String Variant*

Chapter 14 Creating Add-In Functions

185

*Use Variant when a single function can accept or return values of different types. A Variant may also be of type vbEmpty. A Variant argument cannot accept a reference to more than one cell. If you need to accept such references, you may use F1AddInArray or F1AddInArrayEx instead.

F1AddInArray
Use the type F1AddInArray when using an area reference as an argument. You must add the Formula One control to your project to use this type. F1AddInArray will only accept a simple referencea reference to a single 2d area. If you specify a 3d area or union reference, the formula evaluator returns #VALUE! without calling the add-in function. Use F1AddInArrayEx for support of 3d area or union references. The members of F1AddInArray are:
Function Rows() As Long Function Cols() As Long Function GetArrayType() As Long Function GetValue(ByVal Row As Long, ByVal Col As Long) Function IterStart() As Boolean Function IterNext() As Boolean Function IterGetValue() As Variant Function IterGetValueEx(Row As Long, Col As Long) As Variant

F1AddInArray.GetArrayType always returns F1AddIn2dArea. You may use IterStart and IterNext in a loop to iterate through the non-empty elements of the array. This can be much faster than examining each element individually when a sparsely populated array is expected.

Example Code
Dim Found As Boolean Found = TheArray.IterStart() While Found Use IterGetValue or IterGetValueEx to retrieve the value of the current element. Found = TheArray.IterNext() Wend

186

Formula One ActiveX Users Guide

F1AddInArrayEx
You may also use the type F1AddInArrayEx when using an area reference as an argument. Like F1AddInArray, F1AddInArrayEx accepts simple 2d area references. However, F1AddInArrayEx also accepts 3d area and union references. To only allow 2d area references, use F1AddInArray. You must add the Formula One control to your project to use this type. The members of F1AddInArrayEx are:
Function Areas() As Long Number of Areas in Array Function Rows(ByVal Area As Long) As Long Nbr Rows in Area Function Cols(ByVal Area As Long) As Long Nbr Cols in Area Function GetArrayType() As Long Function GetValue(ByVal Area As Long, ByVal Row As Long, _ ByVal Col As Long) Function IterStart() As Boolean Function IterNext() As Boolean Function IterGetValue() As Variant Function IterGetValueEx(Area As Long, Row As Long, Col As Long) _ As Variant

F1AddInArrayEx.GetArrayType returns F1AddIn2dArea, F1AddIn3dArea or F1AddInRegion. Note You may use IterStart and IterNext in a loop to iterate through the nonempty elements of the array. This can be much faster than examining each element individually when a sparsely populated array is expected.

Visual Basic Example Add-Ins

Example 1
=ADDTHESE(1,2) All arguments must be ByVal Function AddThese(ByVal X As Double, ByVal Y As Double) _ As Double AddThese = X + Y End Function

Chapter 14 Creating Add-In Functions

187

Example 2
=CONCATENATETHESE("ABC","XYZ") All arguments must be ByVal Function ConcatenateThese(ByVal X As String, _ ByVal Y As String) As String ConcatenateThese = X + Y End Function

Example 3
=SUMOFRANGE(A1:C5) All arguments must be ByVal Function SumOfRange(ByVal Range As F1AddInArrayEx) _ As Double On Error GoTo ErrorHandler Dim Sum As Double Sum = 0 Dim GotOne As Boolean GotOne = Range.IterStart While GotOne Sum = Sum + CDbl(Range.IterGetValue) GotOne = Range.IterNext Wend SumOfRange = Sum Exit Function ErrorHandler: Err.Raise F1AddInValueError End Function

Example 4
=MAKEERROR(TRUNC(RAND()*7)+1) All arguments must be ByVal Function MakeError(ByVal WhichOne As Double) _ As Double Select Case WhichOne Case 1 Err.Raise F1AddInNullError #NULL! Case 2 Err.Raise F1AddInDivZeroError #DIV/0!

188

Formula One ActiveX Users Guide

Case 4 Err.Raise F1AddInRefError #REF! Case 5 Err.Raise F1AddInNameError #NAME? Case 6 Err.Raise F1AddInNumError #NUM! Case 7 Err.Raise F1AddInNaError #N/A Case Else Err.Raise F1AddInValueError #VALUE! End Select End Function

Chapter 14 Creating Add-In Functions

189

Formula One C++ Add-In API

How Add-In Functions Are Declared
Formula One Add-Ins written in C++ implement each add-in function as an individual callback function. They are callback functions because they will not be exported by the DLLthey will be enumerated by a single exported function called F1AddInInit. Each add-in function implementation must adhere to the following declaration:
HRESULT CALLBACK F1AddInFunction( LPVARIANTARG pResult, int nReserved, int nArgs, LPVARIANTARG pArgs);

Where:
pResult

is a pointer to the variant that holds the add-in functions result. is reserved for future use. The add-in function should ignore this

nReserved

argument.
nArgs pArgs

is the number of arguments being passed to the add-in function.

is a pointer to an array of nArgs variants, which are the arguments being passed to the add-in function. The first argument is at index 0, the second is at index 1, etc. If nArgs is 0, then this pointer is invalid.

Note Formula Ones formula evaluator always clears the variants pointed to by pResult and pArgs. The add-in function should not clear these. Return Value The only valid return values for an add-in function are S_OK and E_OUTOFMEMORY. To report a formula evaluation error, set pResults type to VT_ERROR and its value to one of the error codes listed in Formula Evaluation Errors on page 198, and return S_OK.

190

Formula One ActiveX Users Guide

How Add-In Functions Are Exposed to Formula One

The following functions are used to initialize the plug-in for use within Formula One.

F1AddinInit
The add-in DLL must export the F1AddInInit function, which is declared as follows:
extern "C" { HRESULT __declspec(dllexport) __stdcall F1AddInInit( F1AddInRegisterInfoProc RegisterInfoProc, F1AddInRegisterFunctionProc RegisterFunctionProc, int nReserved1, int nReserved2); };

Where:
RegisterInfoProc

points to a callback function implemented by Formula One. F1AddInInit calls this function to provide global information about the add-in DLL such as its name and a short description.

RegisterFunctionProc

also points to a callback function implemented by Formula One. F1AddInInit provides information about the DLLs add-in functions to Formula One by calling this function once for each add-in function that the DLL implements. and nReserved2 are reserved for future use. The add-in should ignore these arguments.

nReserved1

F1AddInRegisterInfoProc
This function is called from the add-ins F1AddinInit code to register information about the add-in. A pointer to this callback is paired to the add-in through the F1AddinInit functions.
HRESULT CALLBACK F1AddInRegisterInfoProc( LPWSTR pwszName, LPWSTR pwszDescription, int nReserved1, int nReserved2);

Where:
pwszName

is a Unicode string specifying the name of the add-in DLL. This should be a short name of (typically) one or two words.

Chapter 14 Creating Add-In Functions

pwszDescription

191

is a Unicode string describing the add-in DLL. This should be a short descriptive phrase, no longer than a single sentence. and nReserved2 must be zero so that the add-in ignores these arguments.

nReserved1

F1AddInRegisterFunctionProc
Each function in the add-in must be registered by calling the F1AddInRegisterFunctionProc function which is paired to the F1AddinInit entry point.
HRESULT CALLBACK F1AddInRegisterFunctionProc( LPWSTR pwszName, int nReserved, F1AddInFunction pFunction, int nArgs);

Where:
pwszName

is a Unicode string specifying the name of the add-in function. It is not case sensitive. must be zero.

nReserved pFunction

points to an add-in function declared according to the description in this chapter.

nArgs

is the number of arguments expected by the function. If the add-in function can accept a variable number of arguments, this should be 1; otherwise, Formula One will not attempt to call the function with any number of arguments other than nArgs.

How Arguments and Return Values Are Passed

Arguments and return values are passed between Formula One and the add-in function using the VARIANT structure. In Formula One, an argument may have any of the following value types:
VT_EMPTY VT_R8 VT_BSTR VT_BOOL VT_ERROR VT_UNKNOWN

Formula One accepts any of the above value types as an add-in functions result except VT_UNKNOWN.

192

Formula One ActiveX Users Guide

When an add-in function encounters an argument of type VT_UNKNOWN, it should use QueryInterface to obtain an interface it can use to retrieve the data. At this time, the only interfaces implemented for this purpose are IF1AddInArray and IF1AddInArrayEx.
s

Query for IF1AddInArray on an argument where you only want to accept two-dimensional area references. Query for IF1AddInArrayEx on an argument where you want to accept threedimensional area references. This interface also provides all the functionality of IF1AddInArray.

If the add-in function fails to obtain a suitable interface through QueryInterface, it should return the formula evaluation error code F1_E_VALUE. See General Design Principles on page 183, for information on returning formula evaluation errors.

IF1AddInArray interface
When an argument to an add-in function is a two-dimensional area reference, Formula One passes that reference to the add-in function as an IF1AddInArray interface. (The IF1AddInArrayEx interface is also implemented; the add-in function may use whichever interface best suits its needs.) IF1AddInArray, not technically an array, provides a mapping mechanism for exposing a range in the workbook. In future versions of Formula One, the same interface may expose true arrays to the add-in function. This section describes the members of IF1AddInArray.

IF1AddInArray::Rows
Returns the number of rows in the array.
int Rows(void);

IF1AddInArray::Cols
Returns the number of columns in the array.
int Cols(void);

IF1AddInArray::GetArrayType
Returns the type of the array.
Int GetArrayType(void);

Return Value IF1AddinArray returns one of the following constants:

Chapter 14 Creating Add-In Functions

193

F1ADDIN_AREA Formula One returns this constant when the argument is a range reference, as in the formula =SUM(A1:C5). F1ADDIN_ARRAY Not implemented in Formula One, this constant would represent an array, as in the Excel formula =SUM({1,2,3;4,5,6}).

IF1AddInArray::GetValue
Retrieves the value of the specified element in the array.
HRESULT GetValue( int int LPVARIANTARG nRow, nCol, pResult);

Where:
nRow nCol

is the row index of the element to be retrieved. is the column index of the element to be retrieved. points to the variant that will receive the elements value.

pResult

Return Value If nSheet, nRow, or nCol fall outside of the arrays boundaries, the return value is F1_E_REF. In this case, pResults variant is also set to F1_E_REF. If the function succeeds, Formula One returns S_OK, and sets pResults variant the value of the specified element in the array.

IF1AddInArray::IterStart IF1AddInArray::IterNext
Iterates through the non-empty elements of the array.
BOOL IterStart(void); BOOL IterNext(void);

To quickly iterate through the non-empty elements of an array, call IF1AddInArray::IterStart for the first element and IF1AddInArray::IterNext for each additional element until either of these functions returns FALSE. During each iteration, call IF1AddInArray::IterGetValue or IF1AddInArray::IterGetValueEx to retrieve the actual data. Formula One returns the elements in an arbitrary order. Routines that care about the location of the data should use IF1AddInArray::IterGetValueEx, which indicates the row and column of the current element. Using these functions may be much faster than individually examining each element in situations where a sparsely-populated array is expected.

194

Formula One ActiveX Users Guide

Return Value TRUE if successful; FALSE if there are no more non-empty elements.
for (BOOL bGotOne = pAddInArray->IterStart(); bGotOne; bGotOne = pAddInArray->IterNext()) { // use IterGetValue or IterGetValueEx to // get the value of the current element }

IF1AddInArray::IterGetValue IF1AddInArray::IterGetValueEx
Retrieves the value of the array element last selected by IF1AddInArray::IterStart or IF1AddInArray::IterNext.
BOOL IterGetValue(LPVARIANTARG BOOL IterGetValueEx( LPINT pRow, LPINT pCol, LPVARIANTARG pResult); pResult);

Where:
pRow pCol

points to an integer that will receive the elements row index. points to an integer that will receive the elements column index. points to the variant that will receive the elements value.

pResult

Return Value If the last value returned by IF1AddInArray::IterStart or IF1AddInArray::IterNext was TRUE, the return value is TRUE. If the last value returned by IF1AddInArray::IterStart or IF1AddInArray::IterNext was FALSE, or if neither of those functions has yet been called, the return value is FALSE. When the return value is FALSE, no values will be placed in pRow, pCol, or pResult.

IF1AddInArrayEx interface
When an argument to an add-in function is a two- or three- dimensional area reference or a union, Formula One passes that reference or union to the add-in function as an IF1AddInArrayEx interface. (For two-dimensional area references, Formula One also implements the IF1AddInArray; the add-in function may use the interface that best suits its needs.)

Chapter 14 Creating Add-In Functions

195

IF1AddInArrayEx, not technically an array, provides a mapping mechanism for exposing a range in the workbook. In future versions of Formula One, the same interface may expose true arrays to the add-in function. This section describes the members of IF1AddInArrayEx.

IF1AddInArrayEx::Areas
Returns the number of areas in the array.
int Areas(void);

IF1AddInArrayEx::Rows
Returns the number of rows in an area of the array.
int Rows( int nArea);

Where:
nArea

is the index of the area whose row count will be returned.

IF1AddInArrayEx::Cols
Returns the number of columns in an area of the array.
int Cols( int nArea);

Where:
nArea

is the index of the area whose column count will be returned.

IF1AddInArrayEx::GetArrayType
Returns the type of the array.
int GetArrayType(void);

Return Value IF1AddInArrayEx returns one of the following constants: F1ADDIN_AREA: Formula One returns this constant when the argument is a 2D area reference, as in the formula =SUM(A1:C5). F1ADDIN_AREA3D: Formula One returns this constant when the argument is a 3D area reference, as in the formula =SUM(Sheet1:Sheet3!A1:C5). F1ADDIN_ARRAY: Not implemented in Formula One, this constant would represent an array, as in the Excel formula =SUM({1,2,3;4,5,6}).

196

Formula One ActiveX Users Guide

F1ADDIN_REGION: Formula One returns this constant when the argument is a region reference, as in the formula =SUM((A1:C5,A10:C12)).

IF1AddInArrayEx::GetValue
Retrieves the value of the specified element in the array.
HRESULT GetValue( int int int LPVARIANTARG nArea, nRow, nCol, pResult);

Where:
nArea nRow nCol

is the area index of the element to be retrieved.

is the row index of the element to be retrieved. is the column index of the element to be retrieved. points to the variant that will receive the elements value.

pResult

Return Value If nArea, nRow, or nCol, fall outside of the arrays boundaries, the return value is F1_E_REF. In this case, pResults variant is also set to F1_E_REF. If the function succeeds, the return value is S_OK, and pResults variant is set to the value of the specified element in the array.

IF1AddInArray::IterStart IF1AddInArray::IterNext
Iterates through the non-empty elements of the array.
BOOL IterStart(void); BOOL IterNext(void);

To quickly iterate through the non-empty elements of an array, call IF1AddInArrayEx::IterStart for the first element and IF1AddInArrayEx::IterNext for each additional element until either of these functions returns FALSE. During each iteration, call IF1AddInArrayEx::IterGetValue or IF1AddInArrayEx::IterGetValueEx to retrieve the actual data. Formula One returns the elements in an arbitrary order. Routines that care about the location of the data should use IF1AddInArrayEx::IterGetValueEx, which indicates the row and column of the current element. Using these functions may be much faster than individually examining each element in situations where a sparsely-populated array is expected.

Chapter 14 Creating Add-In Functions

197

Return Value TRUE if successful; FALSE if there are no more non-empty elements. Example
for (BOOL bGotOne = pAddInArrayEx->IterStart(); bGotOne; bGotOne = pAddInArrayEx->IterNext()) { // use IterGetValue or IterGetValueEx to // get the value of the current element }

IF1AddInArrayEx::IterGetValue IF1AddInArrayEx::IterGetValueEx
Retrieves the value of the array element last selected by IF1AddInArrayEx::IterStart or IF1AddInArrayEx::IterNext.
BOOL IterGetValue(LPVARIANTARG BOOL IterGetValueEx( LPINT pArea, LPINT pRow, LPINT pCol, LPVARIANTARG pResult); pResult);

Where:
pArea pRow pCol

points to an integer that will receive the elements area index.

points to an integer that will receive the elements row index. points to an integer that will receive the elements column index. points to the variant that will receive the elements value.

pResult

Return Value If the last value returned by IF1AddInArrayEx::IterStart or IF1AddInArrayEx::IterNext was TRUE, the return value is TRUE. If the last value returned by IF1AddInArrayEx::IterStart or IF1AddInArrayEx::IterNext was FALSE, or if neither of those functions has yet been called, the return value is FALSE. When the return value is FALSE, no values will be placed in pRow, pCol, or pResult.

198

Formula One ActiveX Users Guide

Formula Evaluation Errors

An argument to or return value of an add-in function of the type VT_ERROR indicates a formula evaluation error. The errors recognized by Formula One are:
Value F1_E_NULL F1_E_DIVZERO F1_E_VALUE F1_E_REF F1_E_NAME F1_E_NUM F1_E_NA Error Type #NULL! #DIV/0! #VALUE! #REF! #NAME? #NUM! #N/A

C++ Example Add-In

#include <windows.h> #include <initguid.h> #include "f1addin.h" . . . //////////////////////////////////////////////////////////////////// // RETURN.ME function (::ReturnMe) // // RETURN.ME accepts a single argument and returns that arguments // value. If the argument is a range reference, the top-left cells // value is returned. // HRESULT CALLBACK ReturnMe( LPVARIANTARG pResult, // Pointer to the VARIANT receiving // the functions result int, // Ignore this argument; its // reserved for future use int nArgs, // Number of arguments LPVARIANTARG pArgs) // Pointer to an array of nArgs // VARIANTs, each corresponding to // an argument being passed to the // add-in function. pArgs[0] is the // first (left-most) argument. { if (nArgs == 1) { // VT_UNKNOWN requires special handling if (pArgs[0].vt == VT_UNKNOWN) {

Chapter 14 Creating Add-In Functions

199

// We handle arrays; we dont know about any other // interfaces, so all others are ignored here. IF1AddInArrayEx* pArray; if (SUCCEEDED(pArgs[0].punkVal>QueryInterface( IID_IF1AddInArrayEx, (LPVOID*)&pArray))) { // Copy the value of the top-left cell of the first // sheet or range to the result. pArray->GetValue(0, 0, 0, pResult); pArray->Release(); return S_OK; } } else // Copy the arguments value to the result. return ::CheckReturnValue(::VariantCopy(pResult, pArgs)); } return ::MakeErrorResult(pResult, F1_E_VALUE); } //////////////////////////////////////////////////////////////////// // GET.IN.RANGE function (::GetInRange) // // GET.IN.RANGE returns an item at a specified location // with a range. // Formula Cell Returned // -----------------------------------------------------// =GET.IN.RANGE(A11:C13,1,1) A11 // =GET.IN.RANGE(A11:C13,2,3) C12 // =GET.IN.RANGE(Sheet1:Sheet3!A11:C13,2,1,3) Sheet2!C11 // =GET.IN.RANGE((A1:C3,A11:C13),1,3,2) B3 // HRESULT CALLBACK GetInRange( LPVARIANTARG pResult, int, int nArgs, LPVARIANTARG pArgs) { if (nArgs == 3) { IF1AddInArray* pArray; // Try to get the array interface if (pArgs[0].vt == VT_UNKNOWN && SUCCEEDED( pArgs[0].punkVal->QueryInterface(IID_IF1AddInArray, (LPVOID*)&pArray))) { // Both coordinates must be of type double if (pArgs[1].vt == VT_R8 && pArgs[2].vt == VT_R8) { // If the coordinates are invalid, GetValue will put // #REF! in pResult, which is what we want.

200

Formula One ActiveX Users Guide

pArray->GetValue((int)pArgs[1].dblVal - 1, (int)pArgs[2].dblVal - 1, pResult); pArray->Release(); return S_OK; } // Release the array; we cant use it. pArray->Release(); } } else if (nArgs == 4) // Four arguments: a three-dimensional // array { IF1AddInArrayEx* pArray; // Try to get the array interface if (pArgs[0].vt == VT_UNKNOWN && SUCCEEDED( pArgs[0].punkVal->QueryInterface(IID_IF1AddInArrayEx, (LPVOID*)&pArray))) { // All coordinates must be of type double if (pArgs[1].vt == VT_R8 && pArgs[2].vt == VT_R8 && pArgs[3].vt == VT_R8) { pArray->GetValue((int)pArgs[1].dblVal - 1, (int)pArgs[2].dblVal - 1, (int)pArgs[3].dblVal - 1, pResult); pArray->Release(); return S_OK; } pArray->Release(); } } return ::MakeErrorResult(pResult, F1_E_VALUE); } //////////////////////////////////////////////////////////////////// // F1AddInInit // // This exported function (see AddIn.def) registers the add-ins // functions and other general information with Formula One. // Formula One calls this function when it loads the add-in. // HRESULT __stdcall F1AddInInit( F1AddInRegisterInfoProc RegisterInfoProc, F1AddInRegisterFunctionProc RegisterFunctionProc, int, int) { HRESULT hr = S_OK; if (SUCCEEDED(hr))

Chapter 14 Creating Add-In Functions

201

hr = RegisterFunctionProc( L"RETURN.ME", // Name of the function as seen by the // end-user 0, // Reserved for future use; must be 0 ReturnMe, // Name of the function as implemented // in the DLL 1); // Number of arguments expected. if (SUCCEEDED(hr)) hr = RegisterFunctionProc( L"GET.IN.RANGE", 0, GetInRange, -1); if (SUCCEEDED(hr)) hr = RegisterInfoProc( F1AddInName. // // F1AddInDesc, // 0, // 0); //

Name of the add-in (defined at top of the file) Description of the add-in Reserved for future use; must be 0 Reserved for future use; must be 0

return hr; } //////////////////////////////////////////////////////////////////// // DllMain // // Initialization may be done here or in F1AddInInit--whichever best // suits your needs. See the Win32 API doc for more details about // this function. // BOOL APIENTRY DllMain(HANDLE hModule, DWORD ul_reason_for_call, LPVOID lpReserved) { return TRUE; }

Tidestone

Chapter 14 A-Z Worksheet Function Reference

203

C H A P T E R

1 4

A-Z Worksheet Function Reference

This chapter provides a complete alphabetical reference for the Formula One worksheet functions. Refer to Working With Datain this manual for additional information about using worksheet functions.

ABS
Description Syntax Returns the absolute value of a number. ABS ( number )
Parameter number Description Any number.

Remarks Examples

An absolute value does not display a positive or negative sign. These functions both return 1:
ABS(1) ABS(1)

See Also

SIGN

ACOS
Description Syntax Returns the arc cosine of a number. ACOS ( number )
Parameter number Description The cosine of the angle. The cosine can range from 1 to 1.

204

Formula One ActiveX Users Guide

Remarks Examples

The resulting angle is returned in radians (from 0 to ). To convert the resulting radians to degrees, multiply the radians by 180/PI( ). This function returns 1.05:
ACOS(.5)

This function returns 1.77:

ACOS(.2)

See Also

COS

ACOSH
Description Syntax Returns the inverse hyperbolic cosine of a number. ACOSH ( number )
Parameter number Description Any number equal to or greater than 1.

Examples

This function returns .62:

ACOSH(1.2)

This function returns 1.76:

ACOSH (3)

See Also

ASINH ATANH COSH

Chapter 14 A-Z Worksheet Function Reference

205

ADDRESS
Description Syntax Creates a cell address as text. ADDRESS ( row, column, ref_type [, a1] [, sheet] )
Parameter row column ref_type Description The row number for the cell address. The column number for the cell address. The cell reference type. Following are the valid values for this argument. Value Description 1 2 3 4 a1 Absolute Absolute row, relative column Relative row, absolute column Relative

The reference format. This argument must be TRUE( ) to represent an A1 reference format; Formula One does not support the R1C1 reference format. The name of an external worksheet view control. Omitting this argument assumes that the reference exists in the current spreadsheet.

sheet

Examples

This function returns $F$5:

ADDRESS(5, 6, 1)

This function returns SALES!F5:

ADDRESS(5, 6, 4, TRUE(), SALES.)

See Also

COLUMN OFFSET ROW

206

Formula One ActiveX Users Guide

AND
Description Syntax Returns True if all arguments are true; returns False if at least one argument is false. AND ( logical_list )
Parameter logical_list Description A list of conditions separated by commas. You can include as many as 30 conditions in the list. The list can contain logical values or a reference to a range containing logical values. Text and empty cells are ignored. If there are no logical values in the list, the error #VALUE! is returned.

Examples

This function returns True because both arguments are true:

AND(1+1=2, 5+5=10)

This function returns False:

AND(TRUE(), FALSE())

See Also

NOT OR ROW

ASC
Description In DBCS (Far-East) systems, this functions returns a copy of text in which the double-byte characters are converted to single-byte characters, if possible. Characters that cannot be converted are left unchanged. ASC ( text )
Parameter text Description Text converted from double-byte characters to single-byte characters.

Syntax

Remarks See Also

On non-DBCS systems, the text returns unchanged. DBCS

Chapter 14 A-Z Worksheet Function Reference

207

ASIN
Description Syntax Returns the arcsine of a number. ASIN ( number )
Parameter number Description The sine of the resulting angle, ranging from 1 to 1.

Remarks Examples

The resulting angle is returned in radians (ranging from /2 to /2). To convert the resulting radians to degrees, multiply the radians by 180/PI(). This function returns 1.57:
ASIN(1)

This function returns .41:

ASIN(.4)

See Also

ASINH PI SIN

ASINH
Description Syntax Returns the inverse hyperbolic sine of a number. ASINH ( number )
Parameter number Description Any number.

Examples

This function returns 2.37:

ASINH(5.3)

This function returns 2.09:

ASINH(4)

See Also

ACOSH ASIN ATANH SINH

208

Formula One ActiveX Users Guide

ATAN
Description Syntax Returns the arctangent of a number. ATAN ( number )
Parameter number Description The tangent of the angle.

Remarks Examples

The resulting angle is returned in radians, ranging from /2 to /2. To convert the resulting radians to degrees, multiply the radians by 180/PI( ). This function returns 1.29:
ATAN(3.5)

This function returns 1.33:

ATAN(4)

See Also

ATAN2 ATANH PI TAN

ATAN2
Description Syntax Returns the arctangent of the specified coordinates. ATAN2 ( x, y )
Parameter x y Description The x coordinate. The y coordinate.

Remarks

The arctangent is the angle from the x axis to a line with end points at the origin (0, 0) and a point with the given coordinates (x, y). The angle is returned in radians, ranging from to , excluding . This function returns 1.11:
ATAN2(3, 6)

Examples

This function returns 3.04:

ATAN2(1, .1)

See Also

ATAN2

Chapter 14 A-Z Worksheet Function Reference

209

ATANH PI TAN

ATANH
Description Syntax Returns the inverse hyperbolic tangent of a number. ATANH ( number )
Parameter number Description A number between 1 and 1, excluding 1 and 1.

Examples

This function returns .55:

ATANH(.5)

This function returns .26:

ATANH(.25)

See Also

ACOS ASINH TANH

AVERAGE
Description Syntax Returns the average of the supplied numbers. The result of AVERAGE is also known as the arithmetic mean. AVERAGE ( number_list )
Parameter number_list Description A list of numbers separated by commas. As many as 30 numbers can be included in the list, and the list can contain numbers or a reference to a range that contains numbers. Text, logical expressions, or empty cells in a referenced range are ignored. All numeric values (including 0) are used.

Examples

This function returns 8.25:

AVERAGE(5, 6, 8, 14)

210

Formula One ActiveX Users Guide

This function returns 134, the average of the values in the range C15:C17:
AVERAGE(C15:C17)

See Also

MIN MAX

CALL
Description Calls a procedure in a dynamic link library. There are two syntax forms of this function. When CALL is used with REGISTER.ID, as shown in syntax 1, the DLL is loaded and remains loaded until the program is dismissed. When CALL is used alone, as shown in syntax 2, the DLL is loaded, the function is called, and then the DLL is unloaded. Important This function is provided for advanced users only. If you use the CALL function incorrectly, you could cause errors that will require you to restart your computer. Syntax 1 Used with REGISTER.ID CALL(register_id, argument1, ...) Syntax 2 Used alone CALL(module_text, procedure, type_text, argument1, ...)
Parameter register_id argument1 module_text procedure Description The value returned by a previously executed REGISTER.ID function. The arguments to be passed to the procedure. Quoted text or reference specifying the name of the dynamic link library (DLL) that contains the procedure. Text specifying the name of the function in the DLL in Formula One. The function name is case dependent in Formula One. Text specifying the data type of the return value and the data types of all arguments to the DLL or code resource. The first letter of type_text specifies the return value. The data types you use for type_text are described in the following table.

type_text

Chapter 14 A-Z Worksheet Function Reference

Data Type A B C D Description Logical (False = 0, True = 1) IEEE 8-byte floating point number Null-terminated string (255 characters maximum Byte-counted string (first byte contains string length; 255 characters maximum) IEEE 8-byte floating point number Null-terminated string (255 characters maximum) Byte-counted string (first byte contains string length; 255 characters maximum) Unsigned 2-byte integer Signed 2-byte integer Signed 4-byte integer Logical (False = 0, True = 1) Signed 2-byte integer Signed 4-byte integer Pass by Value Value Reference Reference C Declaration short int double char* unsigned char*

211

E F G

Reference Reference Reference

double* char* unsigned char *

H I J L M N

Value Value Value Reference Reference Reference

unsigned short int short int long int short int * short int * long int *

Remarks

For declarations made in C, it is assumed that your compiler defaults to 8-byte doubles, 2-byte short integers, and 4-byte long integers. In the Windows programming environment, all pointers should be far pointers. Pascal calling conventions are used for all functions called from DLLs. For most C compilers, you must add the Pascal keyword to the function declaration. If the return value for your custom function uses a pass-by-reference data type, a null pointer can be passed as the return value. The null pointer is interpreted as the #NUM! error value. For the F and G data types, a custom function can modify an allocated string buffer. If the return value type code is F or G, the value returned by the function is ignored. The list of function arguments is searched for the first data type that corresponds to the return value type. The current contents of the allocated string buffer is taken for the return value. 256 bytes is allocated for the argument; therefore, a function can return a larger string than it receives. You can use a single digit (n), with a value from 1 to 9, as the code for data_type. The variable in the location pointed to by the nth argument is modified instead of the return value; this process is referred to as modifying in place. The nth argument must be a pass-by-reference data type. In addition, you must declare the function void. For most C compilers, you can add the Void keyword to the function declaration.

212

Formula One ActiveX Users Guide

Examples

Syntax 1 The following macro formula registers the GetTickCount function from 32-bit Microsoft Windows. GetTickCount returns the number of milliseconds that have elapsed since Microsoft Windows was started.
REGISTER.ID("Kernel32","GetTickCount","J")

Assuming that this REGISTER.ID function is in cell A5, after your macro registers GetTickCount, you can use the CALL function to return the number of milliseconds that have elapsed since Windows was started:
CALL(A5)

Syntax 2 On a worksheet, you can use the following CALL formula (syntax 2) to call the GetTickCount function:
CALL("Kernel32","GetTickCount","J!")

The ! in the type_text argument forces Formula One to recalculate the CALL function every time the worksheet recalculates. This updates the elapsed time whenever the worksheet recalculates.

CEILING
Description Syntax Rounds a number up to the nearest multiple of a specified significance. CEILING ( number, significance )
Parameter number significance Description The value to round. The multiple to which to round.

Remarks

Regardless of the sign of the number, the value is rounded up, away from zero. If number is an exact multiple of significance, no rounding occurs. If number or significance is non-numeric, the error #VALUE! is returned. When the arguments have opposite signs, the error #NUM! is returned.

Examples

This function returns 1.25:

CEILING(1.23459, .05)

This function returns 150:

CEILING(148.24, 2)

Chapter 14 A-Z Worksheet Function Reference

213

See Also

EVEN FLOOR INT ODD ROUND TRUNC

CHAR
Description Syntax Returns a character that corresponds to the supplied ASCII code. CHAR ( number )
Parameter number Description A value between 1 and 255 that specifies an ASCII character.

Remarks Examples

The character and associated numeric code are defined by Windows in the ASCII character set. This function returns F:
CHAR(70)

This function returns #:

CHAR(35)

See Also

CODE

214

Formula One ActiveX Users Guide

CHOOSE
Description Syntax Returns a value from a list of numbers based on the index number supplied. CHOOSE ( index, item_list )
Parameter index item_list Description A number that refers to an item in item_list. A list of numbers, formulas, or text separated by commas. This argument can also be a range reference. You can specify as many as 29 items in the list.

Remarks

Index can be a cell reference; index can also be a formula that returns any value from 1 to 29. If index is less than 1 or greater than the number of items in item_list, #VALUE! is returned. If index is a fractional number, it is truncated to an integer. This function returns Q2:
CHOOSE(2,Q1, Q2, Q3, Q4)

Examples

This function returns the average of the contents of range A1:A10:

AVERAGE(CHOOSE(1, A1:A10, B1:B10, C1:C10))

See Also

INDEX

Chapter 14 A-Z Worksheet Function Reference

215

CLEAN
Description Syntax Removes all nonprintable characters from the supplied text. CLEAN ( text )
Parameter text Description Any worksheet information.

Remarks Examples

Text that is imported from another environment may require this function. This function returns Payments Due because the character returned by CHAR (8) is nonprintable:
CLEAN(Payments & CHAR(8) & Due)

See Also

CHAR TRIM

CODE
Description Syntax Returns a numeric code representing the first character of the supplied string. CODE ( text )
Parameter text Description Any string.

Remarks Examples

The numeric code and associated string are defined in your computers character set. This function returns 65:
CODE(A)

This function returns 98:

CODE(b)

See Also

CHAR

216

Formula One ActiveX Users Guide

COLUMN
Description Syntax Returns the column number of the supplied reference. COLUMN ( reference )
Parameter reference Description A reference to a cell or range. Omitting the argument returns the number of the column in which COLUMN is placed.

Examples

This function returns 2:

COLUMN(B3)

This function returns 4 if the function is entered in cell D2:

COLUMN()

See Also

COLUMNS ROW

COLUMNS
Description Syntax Returns the number of columns in a range reference. COLUMNS ( range )
Parameter range Description A reference to a range of cells.

Example

This function returns 4:

COLUMNS(A1:D5)

See Also

COLUMN ROWS

Chapter 14 A-Z Worksheet Function Reference

217

CONCATENATE
Description Syntax Joins several text items into one item. CONCATENATE ( text1, text2, ....)
Parameter text1, text2, ... Description Up to 30 text items to be joined into a single text item. The text items can be strings, numbers, or single-cell references.

Remarks Examples

The & operator can be used instead of CONCATENATE to join text items. The following example returns Sale Price it is the same as typing Sale& & Price:
CONCATENATE ("Sale ", "Price")

Suppose in an inventory worksheet, C2 contains extruder1, C5 contains gaskets, and C8 contains the number 15. The following example returns Inventory currently holds 15 gaskets for extruder1.:
CONCATENATE ("Inventory currently holds ", C8, " ", C5," for ", C2)

See Also

COLUMN ROWS

COS
Description Syntax Returns the cosine of an angle. COS ( number )
Parameter number Description The angle in radians. If the angle is in degrees, convert the angle to radians by multiplying the angle by PI()/180.

Examples

This function returns .126:

COS(1.444)

This function returns .28:

COS(5)

218

Formula One ActiveX Users Guide

See Also

ACOS ASINH ATANH COSH PI

COSH
Description Syntax Returns the hyperbolic cosine of a number. COSH ( number )
Parameter number Description Any number.

Examples

This function returns 4.14:

COSH(2.10)

This function returns 1.03:

COSH(.24)

See Also

ASINH ATANH COS

COUNT
Description Syntax Returns the number of values in the supplied list. COUNT ( value_list )
Parameter value_list Description A list of values. The list can contain as many as 30 values.

Remarks

COUNT only numerates numbers or numerical values such as logical values, dates, or text representations of dates. If you supply a range, only numbers and numerical values in the range are counted. Empty cells, logical values, text, and error values in the range are ignored.

Chapter 14 A-Z Worksheet Function Reference

219

Examples

This function returns 2:

COUNT(5, 6, Q2)

This function returns 3:

COUNT(03/06/94, 06/21/94, 10/19/94)

See Also

AVERAGE COUNTA SUM

COUNTA
Description Syntax Returns the number of nonblank values in the supplied list. COUNTA ( expression_list )
Parameter expression_list Description A list of expressions. As many as 30 expressions can be included in the list.

Remarks Examples

COUNTA returns the number of cells that contain data in a range. Null values ( ) are counted, but references to empty cells are ignored. This function returns 4:
COUNTA(32, 45, "Earnings", "")

This function returns 0 when the specified range contains empty cells:
COUNTA(C38:C40)

See Also

AVERAGE COUNT PRODUCT SUM

220

Formula One ActiveX Users Guide

COUNTIF
Description Syntax Returns the number of cells within a range which meet the given criteria. COUNTIF ( range, criteria )
Parameter range criteria Description Range of cells you want to count. Number, expression, or text that defines which cells are counted.

See Also

AVERAGE COUNTA SUM SUMIF

DATE
Description Syntax Returns the serial number of the supplied date. DATE ( year, month, day )
Parameter year Description A number from 1900 to 2078. If year is between 1920 to 2019, you can specify two digits to represent the year; otherwise specify all four digits. A number representing the month (for example, 12 represents December). If a number greater than 12 is supplied, the number is added to the first month of the specified year. A number representing the day of the month. If the number you specify for day exceeds the number of days in that month, the number is added to the first day of the specified month.

month

day

Examples

This function returns 34506:

DATE(94, 6, 21)

This function returns 36225:

DATE(99, 3, 6)

See Also

DATEVALUE DAY MONTH NOW TIMEVALUE TODAY

Chapter 14 A-Z Worksheet Function Reference

221

YEAR

DATEVALUE
Description Syntax Returns the serial number of a date supplied as a text string. DATEVALUE ( text )
Parameter text Description A date in text format between January 1, 1900, and December 31, 2078. If you omit the year, the current year is used.

Examples

This function returns 34399:

DATEVALUE("3/6/94")

This function returns 35058:

DATEVALUE("12/25/95")

See Also

NOW TIMEVALUE TODAY

DAY
Description Syntax Returns the day of the month that corresponds to the date represented by the supplied number. DAY ( serial_number )
Parameter serial_number Description A date represented as a serial number or as text (for example, 06-21-94 or 21-Jun-94).

Examples

This function returns 6:

DAY(34399)

This function returns 21:

DAY("06-21-94")

222

Formula One ActiveX Users Guide

See Also

NOW HOUR MINUTE MONTH SECOND TODAY WEEKDAY YEAR

DAYS360
Description Returns the number of days between two dates based on a 360-day year (twelve 30day months). Use this function to help compute payments if your accounting system is based on twelve 30-day months. DAYS360 (start_date, end_date, [ method ] )
Parameter start_date, end_date method Description The two dates between which you want to know the number of days. A logical value that specifies whether the European or US method should be used in the calculation. If False (or omitted), the US (NASD) method is used. If True, the European method is used. The default is based on the local translation. It should be correct for your location.

Syntax

Remarks

start_date and end_date can be text strings using numbers to represent the month, day, and year (for example, 1/30/93 or 1-30-93), or they can be serial numbers representing the dates. If start_date occurs after end_date, DAYS360 returns a negative number. If method is set to False and start_date is the 31st of a month, it becomes equal to the 30th of the same month. If end_date is the 31st of a month and start_date is less than the 30th of a month, the ending date becomes equal to the 1st of the next month, otherwise the ending date becomes equal to the 30th of the same month. If method is set to True, start_dates or end_dates which occur on the 31st of a month become equal to the 30th of the same month. Note To determine the number of days between two dates in a normal year, you can use normal subtraction--for example, 12/31/93-1/1/93 equals 364.

Example

DAYS360("1/30/93", "2/1/93") equals 1

Chapter 14 A-Z Worksheet Function Reference

223

DB
Description Syntax Returns the real depreciation of an asset for a specific period of time using the fixeddeclining balance method. DB ( cost, salvage, life, period [, months] )
Parameter cost salvage life period months Description The initial cost of the asset. The salvage value of the asset. The number of periods in the useful life of the asset. The period for which to calculate the depreciation. The time units used to determine period and life must match. The number of months in the first year of the items life. Omitting this argument assumes there are 12 months in the first year.

Example

This function returns 1451.52:

DB(10000, 1000, 7, 3)

See Also

DDB SLN SYD VDB

DBCS
Description In DBCS (Far-East) systems, this functions returns a copy of text in which the singlebyte characters are converted to double-byte characters, if possible. Characters that cannot be converted are left unchanged. ASC ( text )
Parameter text Description Text converted from single-byte characters to double-byte characters.

Syntax

Remarks See Also

On non-DBCS systems, the text returns unchanged. ASC

224

Formula One ActiveX Users Guide

DDB
Description Syntax Returns the depreciation of an asset for a specific period of time using the doubledeclining balance method or a declining balance factor you supply. DDB ( cost, salvage, life, period [, factor] )
Parameter cost salvage life period factor Description The initial cost of the asset. The salvage value of the asset. The number of periods in the useful life of the asset. The period for which to calculate the depreciation. The time units used to determine period and life must match. The rate at which the balance declines. Omitting this argument assumes a default factor of 2, the double-declining balance factor.

Remarks

The double-declining balance method uses an accelerated rate where the highest depreciation occurs in the first period, decreasing in successive periods. All arguments for this function must be positive numbers.

Example

This function returns 1457.73:

DDB(10000,1000, 7, 3)

See Also

DB SLN SYD VDB

DOLLAR
Description Syntax Returns the specified number as text, using the local currency format and the supplied precision. DOLLAR ( number [, precision] )
Parameter number precision Description A number, a formula that evaluates to a number, or a reference to a cell that contains a number. A value representing the number of decimal places to the right of the decimal point. Omitting this argument assumes two decimal places.

Chapter 14 A-Z Worksheet Function Reference

225

Note Local currency refers to the currency format for the current system, i.e., the one specified in Regional Settings in Control Panel Remarks Dollar will return the specified number format as text using currency format for the current system. If you wish to always convert to the US Dollar format, regardless of the language of your system, then use the USDOLLAR worksheet function. When using a US setting in Windows, this function returns $1023.79:
DOLLAR(1023.789)

US Example

This function returns $500:

DOLLAR(495.301, 2)

UK Example

When using a British setting in Windows, this function returns 1023.8:

DOLLAR(1023.789)

This function returns 500:

DOLLAR(495.301, -2)

German Example

When using a German setting in Windows, this function returns 1023,8 DM

DOLLAR(1023.789)

This function returns 500 DM:

DOLLAR(495.301, 2)

See Also

FIXED TEXT VALUE USDOLLAR

ERROR.TYPE
Description Syntax Returns a number corresponding to an error. ERROR.TYPE ( error_ref )
Parameter error_ref Description A cell reference.

226

Formula One ActiveX Users Guide

Remarks

The following error text or numbers can be returned by this function.

Number 1 2 3 4 5 6 7 #N/A Description #NULL! #DIV/0! #VALUE! #REF! #NAME? #NUM! #N/A Other

Example

This function returns 2 if the formula in cell A1 attempts to divide by zero:

ERROR.TYPE(A1)

See Also

ISERR ISERROR

EVEN
Description Syntax Rounds the specified number up to the nearest even integer. EVEN ( number )
Parameter number Description Any number, a formula that evaluates to a number, or a reference to a cell that contains a number.

Examples

This function returns 4:

EVEN(2.5)

This function returns 2032:

EVEN(2030.45)

See Also

CEILING FLOOR INT ODD ROUND TRUNC

Chapter 14 A-Z Worksheet Function Reference

227

EXACT
Description Syntax Compares two expressions for identical, case-sensitive matches. True is returned if the expressions are identical; False is returned if they are not. EXACT ( expression1, expression2 )
Parameter expression1 expression2 Description Any text. Any text.

Examples

This function returns True:

EXACT("Match", "Match")

This function returns False:

EXACT("Match", "match")

See Also

LEN SEARCH

EXP
Description Syntax Returns e raised to the specified power. The constant e is 2.71828182845904 (the base of the natural logarithm). EXP ( number )
Parameter number Description Any number as the exponent.

Examples

This function returns 12.18:

EXP(2.5)

This function returns 20.09:

EXP(3)

See Also

LN LOG

228

Formula One ActiveX Users Guide

FACT
Description Syntax Returns the factorial of a specified number. FACT ( number )
Parameter number Description Any non-negative integer. If you supply a real number, FACT truncates the number to an integer before calculation.

Examples

This function returns 2:

FACT(2.5)

This function returns 720:

FACT(6)

See Also

PRODUCT

FALSE
Description Syntax See Also Returns the logical value False. This function always requires the trailing parentheses. FALSE ( ) TRUE

FIND
Description Syntax Searches for a string of text within another text string and returns the character position at which the search string first occurs. FIND ( search_text, text [, start_position] )
Parameter search_text text start_position Description The text to find. If you specify an empty string (""), FIND matches the first character in text. The text to be searched. The character position in text where the search begins. The first character in text is character number 1. When you omit this argument, the default starting position is character number 1.

Chapter 14 A-Z Worksheet Function Reference

229

Remarks Examples

FIND is case-sensitive. You cannot use wildcard characters in the search_text. This function returns 12:
FIND("time", "Theres no time like the present")

This function returns 19:

FIND("4", "Aisle 4, Part 123-4-11", 9)

See Also

EXACT LEN MID SEARCH

FINDB
Description Syntax Searches for a string of text within another text string and returns the byte position at which the search string first occurs. FINDB ( search_text, text [, start_position] )
Parameter search_text text start_position Description The text to find. If you specify an empty string (""), FINDB matches the first byte in text. The text to be searched. The byte position in text where the search begins. The first byte in text is byte number 1. When you omit this argument, the default starting position is byte number 1.

Remarks

FINDB is case-sensitive. You cannot use wildcard characters in the search_text. start_position and return value are expressed in bytes, so these values might differ on DBCS systems. On non-DBCS systems, these functions are identical, but FINDB should only be used in special applications that require distinctions between singlebyte and double-byte characters.

Examples

This function returns 12:

FINDB("time", "Theres no time like the present")

This function returns 19:

FINDB("4", "Aisle 4, Part 123-4-11", 9)

230

Formula One ActiveX Users Guide

FIXED
Description Syntax Rounds a number to the supplied precision, formats the number in decimal format, and returns the result as text. FIXED ( number [, precision][, no_commas] )
Parameter number precision Description Any number. The number of digits that appear to the right of the decimal place. When this argument is omitted, a default precision of 2 is used. If you specify negative precision, number is rounded to the left of the decimal point. You can specify a precision as great as 127 digits. Determines if thousands separators (commas) are used in the result. Use 1 to exclude commas in the result. If no_commas is 0 or the argument is omitted, thousands separators are included (for example, 1,000.00).

no_commas

Examples

This function returns 2,000.500:

FIXED(2000.5, 3)

This function returns 2010:

FIXED(2009.5, 1, 1)

See Also

DOLLAR ROUND TEXT VALUE

FLOOR
Description Syntax Rounds a number down to the nearest multiple of a specified significance. FLOOR (number, significance )
Parameter number significance Description The value to round. The multiple to which to round.

Remarks

Regardless of the sign of the number, the value is rounded down, toward zero. If number is an exact multiple of significance, no rounding occurs. If number or significance is non-numeric, #NAME? is returned. When the arguments have opposite signs, #NUM! is returned.

Chapter 14 A-Z Worksheet Function Reference

231

Examples

This function returns 1.2:

FLOOR(1.23459, .05)

This function returns 148:

FLOOR(148.24, 2)

See Also

CEILING EVEN INT ODD ROUND TRUNC

FV
Description Syntax Returns the future value of an annuity based on regular payments and a fixed interest rate. FV ( interest, nper, payment [, pv] [, type] )
Parameter interest nper payment pv Description The fixed interest rate. The number of payments in an annuity. The fixed payment made each period. The present value, or the lump sum amount, the annuity is currently worth. When you omit this argument, a present value of 0 is assumed. Indicates when payments are due. Use 0 if payments are due at the end of the period or 1 if payments are due at the beginning of the period. When you omit this argument, 0 is assumed.

type

Remarks

The units used for interest must match those used for nper. For example, if the annuity has an 8 percent annual interest rate over a period of 5 years, specify 8 percent/12 for interest and 5*12 for nper. Cash paid out, such as a payment, is shown as a negative number. Cash received, such as a dividend check, is shown as a positive number.

Examples

This function returns 4,774.55:

FV(5%, 8, 500)

This function returns 531,550.86:

FV(10%/12, 240, 700, 1)

232

Formula One ActiveX Users Guide

See Also

IPMT NPER PMT PPMT PV RATE

HLOOKUP
Description Syntax Searches the top row of a table for a value and returns the contents of a cell in that table that corresponds to the location of the search value. HLOOKUP ( search_item, search_range, row_index )
Parameter search_item search_range Description A value, text string, or reference to a cell containing a value that is matched against data in the top row of search_range. A reference to the range (table) to be searched. The cells in the first row of search_range can contain numbers, text, or logical values. The contents of the first row must be in ascending order (for example, 2, 1, 0, 2...A through Z, False, True). Text searches are not case-sensitive. The row in search_range from which the matching value is returned. row_index can be a number from 1 to the number of rows in search_range. If row_index is less than 1, the error #VALUE! is returned. When row_index is greater than the number of rows in the table, the error #REF! is returned.

row_index

Remarks

HLOOKUP compares the information in the top row of search_range to the supplied search_item. When a match is found, information located in the same column and supplied row (row_index) is returned. If search_item cannot be found in the top row of search_range, the largest value that is less than search_item is used. When search_item is less than the smallest value in the first row of the search_range, the error #REF! is returned.

Examples

The following examples use this worksheet.

Chapter 14 A-Z Worksheet Function Reference

233

This function returns 22.63:

HLOOKUP("Northeast", B1:E5, 3)

This function returns #REF!:

HLOOKUP("Pacific", B1:E5, 7)

See Also

INDEX LOOKUP MATCH VLOOKUP

HOUR
Description Syntax Returns the hour component of the specified time in 24-hour format. HOUR ( serial_number )
Parameter serial_number Description The time as a serial number. The decimal portion of the number represents time as a fraction of the day.

Remarks Examples

The result is an integer ranging from 0 (12:00 AM) to 23 (11:00 PM). This function returns 9:
HOUR(34259.4)

This function returns 23:

HOUR(34619.976)

See Also

DAY MINUTE MONTH NOW SECOND WEEKDAY YEAR

234

Formula One ActiveX Users Guide

IF
Description Syntax Tests the condition and returns the specified value. IF ( condition, true_value, false_value )
Parameter condition true_value false_value Description Any logical expression. The value to be returned if condition evaluates to True. The value to be returned if condition evaluates to False.

Example

This function returns Greater if the contents of A1 is greater than 10 and Less if the contents of A1 is less than 10:
IF(A1>10, "Greater", "Less")

See Also

AND FALSE NOT OR TRUE

INDEX
Description Syntax Returns the contents of a cell from a specified range. INDEX ( reference [, row] [, column] [, range_number] )
Parameter reference Description A reference to one or more ranges. If reference specifies more than one range, separate each reference with a comma and enclose reference in parentheses. For example, (A1:C6, B7:E14, F4). If each range in reference contains only one row or column, you can omit the row or column argument. For example, if reference is A1:A15, you can omit the column argument INDEX(A1:A15, 3,, 1). The row number in reference from which to return data. Column number in reference from which to return data. Specifies the range from which data is returned if reference contains more than one range. For example, if reference is (A1:A10, B1:B5, D14:E23), A1:A10 is range_number 1, B1:B5 is range_number 2, and D14:E23 is range_number 3.

row column range_number

Chapter 14 A-Z Worksheet Function Reference

235

Remarks

If row, column, and range_number do not point to a cell within reference, #REF! is returned. If row and column are omitted, INDEX returns the range in reference specified by range_number. The following examples use this worksheet.

Examples

This function returns $1415.35:

INDEX(A2:B6, 2, 2)

This function returns $1634.58:

INDEX((A2:B6, D2:E6), 4, 2, 2)

See Also

CHOOSE HLOOKUP LOOKUP MATCH VLOOKUP

INDIRECT
Description Syntax Returns the contents of the cell referenced by the specified cell. INDIRECT ( ref_text [, a1] )
Parameter ref_text a1 Description A reference to a cell that references a third cell. If ref_text is not a valid reference, the error #REF! is returned. The reference format. This argument must be TRUE() to represent an A1 reference format; Formula One does not support the R1C1 reference format.

Example

This function returns the contents of the cell that C1 references. If C1 contains D1, then the contents of D1is returned:
INDIRECT(C1)

236

Formula One ActiveX Users Guide

See Also

OFFSET

INT
Description Syntax Rounds the supplied number down to the nearest integer. INT ( number )
Parameter number Description Any real number.

Examples

This function returns 10:

INT(10.99)

This function returns 11:

INT(10.99)

See Also

CEILING FLOOR MOD ROUND TRUNC

IPMT
Description Syntax Returns the interest payment of an annuity for a given period, based on regular payments and a fixed periodic interest rate. IPMT ( interest, per, nper, pv, [fv], [type] )
Parameter interest per nper pv fv type Description The fixed periodic interest rate. The period for which to return the interest payment. This number must be between 1 and nper. The number of payments. The present value, or the lump sum amount the annuity is currently worth. The future value, or the value after all payments are made. If this argument is omitted, the future value is assumed to be 0. Indicates when payments are due. Use 0 if payments are due at the end of the period or 1 if payments are due at the beginning of the period. When you omit this argument, 0 is assumed.

Chapter 14 A-Z Worksheet Function Reference

237

Remarks

The units used for interest must match those used for nper. For example, if the annuity has an 8 percent annual interest rate over a period of 5 years, specify 8 percent/12 for interest and 5*12 for nper. Cash paid out, such as a payment, is shown as a negative number. Cash received, such as a dividend check, is shown as a positive number.

Examples

This function returns 117.87:

IPMT(8%/12, 2, 48, 18000)

This function returns 117.09:

IPMT(8%/12, 2, 48, 18000, 0, 1)

See Also

FV PMT PPMT RATE

IRR
Description Syntax Returns internal rate of return for a series of periodic cash flows. IRR ( cash_flow [, guess] )
Parameter cash_flow Description A reference to a range that contains values for which to calculate the internal rate of return. The values must contain at least one positive and one negative value. During calculation, IRR uses the order in which the values appear to determine the order of the cash flow. Text, logical values, and empty cells in the range are ignored. The estimate of the internal rate of return. If no argument is supplied, a rate of return of 10 percent is assumed.

guess

Remarks

The internal rate of return is the interest rate received for an investment consisting of payments (specified by negative numbers) and investments (specified by positive numbers). IRR is calculated iteratively, cycling through the calculation until the result is accurate to .00001 percent. If the result cannot be found after 20 iterations, #NUM! is returned. When this occurs, supply a different value for guess.

238

Formula One ActiveX Users Guide

Examples

The following examples use this worksheet.

This function returns 3.72 percent:

IRR(B1:B6)

This function returns 49.26 percent:

IRR(B1:B3, 20%)

See Also

MIRR NPV RATE

ISBLANK
Description Syntax Determines if the specified cell is blank. ISBLANK ( reference )
Parameter reference Description A reference to any cell.

Remarks Example

If the referenced cell is blank, True is returned. False is returned if the cell is not blank. This function returns True if A1 is a blank cell:
ISBLANK(A1)

See Also

ISERR ISERROR ISLOGICAL ISNA ISNONTEXT ISNUMBER ISREF ISTEXT

Chapter 14 A-Z Worksheet Function Reference

239

ISERR
Description Syntax Determines if the specified expression returns an error value. ISERR ( expression )
Parameter expression Description Any expression.

Remarks Example

If the expression returns any error except #N/A!, True is returned. Otherwise, False is returned. This function returns True if A1 contains a formula that returns an error such as #NUM!:
ISERR(A1)

See Also

ISBLANK ISERROR ISLOGICAL ISNA ISNONTEXT ISNUMBER ISREF ISTEXT

ISERROR
Description Syntax Determines if the specified expression returns an error value. ISERROR ( expression )
Parameter expression Description Any expression.

Remarks Examples

If expression returns any error value, such as #N/A!, #VALUE!, #REF!, #DIV/0!, #NUM!, #NAME?, or #NULL!, True is returned. Otherwise, False is returned. This function returns True:
ISERROR(4/0)

This function returns False if A1 contains a formula that does not return an error.
ISERROR(A1)

See Also

ISBLANK

240

Formula One ActiveX Users Guide

ISERR ISLOGICAL ISNA ISNONTEXT ISNUMBER ISREF ISTEXT

ISLOGICAL
Description Syntax Determines if the specified expression returns a logical value. ISLOGICAL ( expression )
Parameter expression Description Any expression.

Remarks Example

If expression returns a logical value, True is returned. Otherwise, False is returned. This function returns True because ISBLANK returns a logical value:
ISLOGICAL(ISBLANK(A1))

See Also

ISBLANK ISERR ISERROR ISNA ISNONTEXT ISNUMBER ISREF ISTEXT

ISNA
Description Syntax Determines if the specified expression returns the value not available error. ISNA ( expression )
Parameter expression Description Any expression.

Remarks Example

If expression returns the #N/A! error, True is returned. Otherwise, False is returned. This function returns True if cell A1 contains the NA ( ) function or returns the error value #N/A!:

Chapter 14 A-Z Worksheet Function Reference

ISNA(A1)

241

See Also

ISBLANK ISERR ISERROR ISLOGICAL ISNONTEXT ISNUMBER ISREF ISTEXT

ISNONTEXT
Description Syntax Determines if the specified expression is not text. ISNONTEXT ( expression )
Parameter expression Description Any expression.

Remarks Examples

If expression returns any value that is not text, True is returned. Otherwise, False is returned. This function returns True if cell F3 contains a number or is a blank cell:
ISNONTEXT(F3)

This function returns False:

ISNONTEXT("text")

See Also

ISBLANK ISERR ISERROR ISLOGICAL ISNA ISNUMBER ISREF ISTEXT

242

Formula One ActiveX Users Guide

ISNUMBER
Description Syntax Determines if the specified expression is a number. ISNUMBER ( expression )
Parameter expression Description Any expression.

Remarks

If expression returns a number, True is returned. Otherwise, False is returned. If expression returns a number represented as text (for example, 12), False is returned. This function returns True:
ISNUMBER(123.45)

Examples

This function returns False:

ISNUMBER("123")

See Also

ISBLANK ISERR ISERROR ISLOGICAL ISNA ISNONTEXT ISREF ISTEXT

ISREF
Description Syntax Determines if the specified expression is a range reference. ISREF ( expression )
Parameter expression Description Any expression.

Remarks Example

If expression returns a range reference, True is returned. Otherwise, False is returned. This function returns True:
ISREF(A3)

See Also

ISBLANK ISERR

Chapter 14 A-Z Worksheet Function Reference

243

ISERROR ISLOGICAL ISNA ISNONTEXT ISTEXT

ISTEXT
Description Syntax Determines if the specified expression is text. ISTEXT ( expression )
Parameter expression Description Any expression.

Remarks Example

If expression returns text, True is returned. Otherwise, False is returned. This function returns True:
ISTEXT("2nd Quarter")

See Also

ISBLANK ISERR ISERROR ISLOGICAL ISNA ISNONTEXT ISNUMBER ISREF

LEFT
Description Syntax Returns the leftmost characters from the specified text string. LEFT ( text [, num_chars] )
Parameter text num_chars Description Any text string. The number of characters to return. This value must be greater than or equal to zero. If num_chars is greater than the number of characters in text, the entire string is returned. Omitting this argument assumes a value of 1.

Examples

This function returns 2:

LEFT("2nd Quarter")

244

Formula One ActiveX Users Guide

This function returns 2nd:

LEFT("2nd Quarter", 3)

See Also

MID RIGHT

LEFTB
Description Syntax Returns the leftmost byte from the specified text string. LEFTB ( text [, num_bytes] )
Parameter text num_bytes Description Any text string. The number of bytes to return. This value must be greater than or equal to zero. If num_bytes is greater than the number of bytes in text, the entire string is returned. Omitting this argument assumes a value of 1.

Remarks

num_bytes and return value are expressed in bytes, so these values might differ on DBCS systems. On non-DBCS systems, these functions are identical, but LEFTB should only be used in special applications that require distinctions between singlebyte and double-byte characters. This function returns 2:
LEFTB("2nd Quarter")

Examples

This function returns 2nd:

LEFTB("2nd Quarter", 3)

LEN
Description Syntax Returns the number of characters in the supplied text string. LEN ( text )
Parameter text Description Any text string. Spaces in the string are counted as characters.

Examples

This function returns 11:

LEN(3rd Quarter)

Chapter 14 A-Z Worksheet Function Reference

245

This function returns 3:

LEN(1-3)

See Also

EXACT SEARCH

LENB
Description Syntax Returns the number of bytes in the supplied text string. LENB ( text )
Parameter text Description Any text string. Spaces in the string are counted as bytes.

Remarks

text and return value are expressed in bytes, so these values might differ on DBCS systems. On non-DBCS systems, these functions are identical, but LENB should only be used in special applications that require distinctions between single-byte and double-byte characters. This function returns 11:
LENB("3rd Quarter")

Examples

This function returns 3:

LENB("1-3")

LN
Description Syntax Returns the natural logarithm (based on the constant e) of a number. LN ( number )
Parameter number Description Any positive real number.

Remarks Examples

LN is the inverse of the EXP function. This function returns 2.50:

LN(12.18)

This function returns 3.00:

LN(20.09)

246

Formula One ActiveX Users Guide

See Also

EXP LOG LOG10

LOG
Description Syntax Returns the logarithm of a number to the specified base. LOG ( number [, base] )
Parameter number base Description Any positive real number. The base of the logarithm. Omitting this argument assumes a base of 10.

Examples

This function returns 0:

LOG(1)

This function returns 1:

LOG(10)

See Also

EXP LN LOG10

LOG10
Description Syntax Returns the base-10 logarithm of a number. LOG10 ( number )
Parameter number Description Any positive real number.

Examples

This function returns 2.41:

LOG10(260)

This function returns 2:

LOG10(100)

See Also

EXP LN

Chapter 14 A-Z Worksheet Function Reference

247

LOG

LOOKUP
Description Syntax Searches for a value in one range and returns the contents of the corresponding position in a second range. LOOKUP ( lookup_value, lookup_range, result_range )
Parameter lookup_value lookup_range Description The value for which to search in the first range. The first range to search and contains only one row or one column. The range can contain numbers, text, or logical values. To search lookup_range correctly, the expressions in the range must be placed in ascending order (for example, 2, 1, 0, 1, 2...A through Z, False, True). The search is not case-sensitive. A range of one row or one column that is the same size as lookup_range.

result_range

Remarks

If lookup_value does not have an exact match in lookup_range, the largest value that is less than or equal to lookup_value is found and the corresponding position in result_range is returned. When lookup_value is smaller than the data in lookup_range, #N/A is returned. The following examples use this worksheet.

Examples

This function returns Detroit:

LOOKUP("North", A2:A7, B2:B7)

This function returns #N/A:

LOOKUP(Alabama, A2:A7, B2:B7)

See Also

HLOOKUP INDEX VLOOKUP

248

Formula One ActiveX Users Guide

LOWER
Description Syntax Changes the characters in the specified string to lowercase characters. Numeric characters in the string are not changed. LOWER ( text )
Parameter text Description Any string.

Examples

This function returns 3rd quarter:

LOWER("3rd Quarter")

This function returns john doe:

LOWER("JOHN DOE")

See Also

PROPER UPPER

Chapter 14 A-Z Worksheet Function Reference

249

MATCH
Description Syntax A specified value is compared against values in a range. The position of the matching value in the search range is returned. MATCH ( lookup_value, lookup_range, comparison )
Parameter lookup_value Description The value against which to compare. It can be a number, text, or logical value or a reference to a cell that contains one of those values. The range to search and contains only one row or one column. The range can contain numbers, text, or logical values. A number that represents the type of comparison to be made between lookup_value and the values in lookup_range. When you omit this argument, comparison method 1 is assumed. When comparison is 1, the largest value that is less than or equal to lookup_value is matched. When using this comparison method, the values in lookup_range must be in ascending order (for example, ...2, 1, 0, 1, 2..., A through Z, False, True). When comparison is 0, the first value that is equal to lookup_value is matched. When using this comparison method, the values in lookup_range can be in any order. When comparison is 1, the smallest value that is greater than or equal to lookup_value is matched. When using this comparison method, the values in lookup_range must be in descending order (for example, True, False, Z through A, ...2, 1, 0, 1, 2...).

lookup_range comparison

Remarks

When using comparison method 0 and lookup_value is text, lookup_value can contain wildcard characters. The wildcard characters are * (asterisk), which matches any sequence of characters, and ? (question mark), which matches any single character. When no match is found for lookup_value, #N/A is returned.

Examples

The following examples use this worksheet.

250

Formula One ActiveX Users Guide

This function returns 5:

MATCH(7600, B2:B7,1)

This function returns 2:

MATCH("D*", A2:A7,0)

See Also

HLOOKUP INDEX LOOKUP VLOOKUP

MAX
Description Syntax Returns the largest value in the specified list of numbers. MAX ( number_list )
Parameter number_list Description A list of as many as 30 numbers, separated by commas. The list can contain numbers, logical values, text representations of numbers, or a reference to a range containing those values. Error values or text that cannot be translated into numbers return errors. If a range reference is included in the list, text, logical expressions, and empty cells in the range are ignored. If there are no numbers in the list, 0 is returned.

Examples

This function returns 500:

MAX(50, 100, 150, 500, 200)

This function returns the largest value in the range:

MAX(A1:F12)

See Also

AVERAGE MIN

Chapter 14 A-Z Worksheet Function Reference

251

MID
Description Syntax Returns the specified number of characters from a text string, beginning with the specified starting position. MID ( text, start_position, num_chars )
Parameter text start_position Description The string from which to return characters. The position of the first character to return from text. If start_position is 1, the first character in text is returned. If start_position is greater than the number of characters in text, an empty string ("") is returned. If start_position is less than 1, #VALUE! is returned. num_chars The number of characters to return. If num_chars is negative, #VALUE! is returned.

Remarks Examples

If start_position plus the number of characters in num_chars exceeds the length of text, the characters from start_position to the end of text are returned. This function returns Expenses:
MID("Travel Expenses", 8, 8)

This function returns 45:

MID("Part #45-7234", 7, 2)

See Also

CODE FIND LEFT RIGHT SEARCH

252

Formula One ActiveX Users Guide

MIDB
Description Syntax Returns the specified number of bytes from a text string, beginning with the specified starting position. MIDB ( text, start_position, num_bytes )
Parameter text start_position Description The string from which to return bytes. The position of the first byte to return from text. If start_position is 1, the first byte in text is returned. If start_position is greater than the number of bytes in text, an empty string ("") is returned. If start_position is less than 1, #VALUE! is returned. num_bytes The number of bytes to return. If num_bytes is negative, #VALUE! is returned.

Remarks

If start_position plus the number of bytes in num_bytes exceeds the length of text, the bytes from start_position to the end of text are returned. start_position, num_bytes, and return value are expressed in bytes, so these values might differ on DBCS systems. On non-DBCS systems, these functions are identical, but MIDB should only be used in special applications that require distinctions between single-byte and double-byte characters.

Examples

This function returns Expenses:

MIDB("Travel Expenses", 8, 8)

This function returns 45:

MIDB("Part #45-7234", 7, 2)

Chapter 14 A-Z Worksheet Function Reference

253

MIN
Description Syntax Returns the smallest value in the specified list of numbers. MIN ( number_list )
Parameter number_list Description A list of as many as 30 numbers, separated by commas. The list can contain numbers, logical values, text representations of numbers, or a reference to a range containing those values. Error values or text that cannot be translated into numbers return errors. If a range reference is included in the list, text, logical expressions, and empty cells in the range are ignored. If there are no numbers in the list, 0 is returned.

Examples

This function returns 50:

MIN(50, 100, 150, 500, 200)

This function returns the smallest value in the range:

MIN(A1:F12)

See Also

AVERAGE MAX

MINUTE
Description Syntax Returns the minute that corresponds to the supplied date. MINUTE ( serial_number )
Parameter serial_number Description The time as a serial number. The decimal portion of the number represents time as a fraction of the day.

Remarks Examples

The result is an integer ranging from 0 to 59. This function returns 36:
MINUTE(34506.4)

This function returns 48:

MINUTE(34399.825)

254

Formula One ActiveX Users Guide

See Also

DAY HOUR MONTH NOW SECOND WEEKDAY YEAR

MIRR
Description Syntax Returns the modified internal rate of return for a series of periodic cash flows. MIRR (cash_flows, finance_rate, reinvest_rate )
Parameter cash_flow Description A reference to a range that contains values for which to calculate the modified internal rate of return. The values must contain at least one positive and one negative value. During calculation, MIRR uses the order in which the values appear to determine the order of cash flow. Values that represent cash received should be positive; negative values represent cash paid. Text, logical values, and empty cells in the range are ignored. finance_rate reinvest_rate The interest rate paid on money used in the cash flow. The interest rate received on money reinvested from the cash flow.

Remarks Examples

The modified internal rate of return considers the cost of the investment and the interest received on the reinvestment of cash. The following examples use this worksheet.

This function returns 5.20 percent:

MIRR(B1:B6, 12%, 8%)

This function returns 40.93 percent:

MIRR(B1:B3, 12%, 8%)

Chapter 14 A-Z Worksheet Function Reference

255

See Also

IRR NPV RATE

MOD
Description Syntax Returns the remainder after dividing a number by a specified divisor. MOD ( number, divisor )
Parameter number divisor Description Any number. Any nonzero number. If divisor is 0, #DIV/0! is returned.

Examples

This function returns 1:

MOD(23, 3)

This function returns 2:

MOD(23, 3)

See Also

INT ROUND TRUNC

MONTH
Description Syntax Returns the month that corresponds to the supplied date. MONTH ( serial_number )
Parameter serial_number Description The date as a serial number or as text (for example, 06-21-94 or 21-Jun-94).

Remarks Examples

MONTH returns a number ranging from 1 (January) to 12 (December). This function returns 6:
MONTH("06-21-94")

This function returns 10:

MONTH(34626)

256

Formula One ActiveX Users Guide

See Also

DAY HOUR MINUTE NOW SECOND TODAY WEEKDAY YEAR

N
Description Syntax Tests the supplied value and returns the value if it is a number. N ( value )
Parameter value Description A value or a reference to a cell containing a value to test.

Remarks

Numbers are returned as numbers, serial numbers formatted as dates are returned as serial numbers, and the logical function TRUE() is returned as 1. All other expressions return 0. This function returns 32467:
N(32467)

Examples

This function returns 1 if A4 contains the logical function TRUE:

N(A4)

See Also

T VALUE

NA
Description Syntax Remarks Returns the error value #N/A, which represents not available. NA ( ) Use NA to mark cells that lack data without leaving them empty. Empty cells may not be correctly represented in some calculations. Although NA does not use arguments, you must supply the empty parentheses to correctly reference the function. See Also ISNA

Chapter 14 A-Z Worksheet Function Reference

257

NOT
Description Syntax Returns a logical value that is the opposite of its value. NOT ( logical )
Parameter logical Description An expression that returns a logical value such as True or False.

Remarks Examples

If logical is false, NOT returns True. Conversely, if logical is true, NOT returns False. This function returns False:
NOT(TRUE())

This function returns False:

NOT(MONTH("12/25/94") = 12)

See Also

AND IF OR

NOW
Description Syntax Remarks Returns the current date and time as a serial number. NOW ( ) In a serial number, numbers to the left of the decimal point represent the date; numbers to the right of the decimal point represent the time. The result of this function changes only when a recalculation of the worksheet occurs. DATE DAY HOUR MINUTE MONTH SECOND TODAY WEEKDAY YEAR

See Also

258

Formula One ActiveX Users Guide

NPER
Description Syntax Returns the number of periods of an investment based on regular periodic payments and a fixed interest rate. NPER ( interest, pmt, pf [, fv] [, type] )
Parameter interest pmt pf fv type Description The fixed interest rate. The fixed payment made each period. Generally, pmt includes the principle and interest, not taxes or other fees. The present value, the lump-sum amount that a series of future payments is currently worth. The future value, the balance to attain after the final payment. Omitting this argument assumes a future balance of 0. Indicates when payments are due. Use 0 if payments are due at the end of the period or 1 if payments are due at the beginning of the period. When you omit this argument, 0 is assumed.

Examples

This function returns 36.67:

NPER(12%/12, 350, 300, 16000, 1)

This function returns 36.98:

NPER(1%, 350, 300, 16000)

See Also

FV IPMT PMT PPMT PV RATE

Chapter 14 A-Z Worksheet Function Reference

259

NPV
Description Syntax Returns the net present value of an investment based on a series of periodic payments and a discount rate. NPV ( discount_rate, value_list )
Parameter discount_rate value_list Description The rate of discount for one period. A list of as many as 29 arguments or a reference to a range that contains values that represent payments and income. During calculation, NPV uses the order in which the values appear to determine the order of cash flow. Numbers, empty cells, and text representations of numbers are included in the calculation. Errors and text that cannot be translated into numbers are ignored. If value_list is a range reference, only numeric data in the range is included in the calculation. Other types of data in the range, such as empty cells, logical values, text, and error values, are ignored.

Remarks

The time span NPV uses for calculation begins one period before the first cash flow date and ends when the last cash flow payment is made. This function is based on future cash flows. When your first cash flow occurs at the beginning of the first period, the first value must be added to the NPV result, not supplied as a value in value_list. This function returns 811.57:
NPV(8%, 12000, 3000, 3000, 3000, 7000)

Example

See Also

FV IRR PV

ODD
Description Syntax Rounds the specified number up to the nearest odd integer. ODD ( number )
Parameter number Description Any number, a formula that evaluates to a number, or a reference to a cell that contains a number.

260

Formula One ActiveX Users Guide

Examples

This function returns 5:

ODD(3.5)

This function returns 7:

ODD(6)

See Also

CEILING EVEN FLOOR INT ROUND TRUNC

OFFSET
Description Syntax Returns the contents of a range that is offset from a starting point in the spreadsheet. OFFSET ( reference, rows, columns [, height] [, width] )
Parameter reference rows Description A reference to a cell from which the offset reference is based. If you specify a range reference, #VALUE! is returned. The number of rows from reference that represents the upper-left cell of the offset range. A positive number represents rows below the starting cell; a negative number represents rows above the starting cell. If rows places the upper-left cell of the offset range outside the spreadsheet boundary, #REF! is returned. The number of columns from reference that represents the upper-left cell of the offset range. A positive number represents columns right of the starting cell; a negative number represents columns left of the starting cell. If columns places the upper-left cell of the offset range outside the spreadsheet boundary, #REF! is returned. A positive number representing the number of rows to include in the offset range. Omitting this argument assumes a single row. A positive number representing the number of columns to include in the offset range. Omitting this argument assumes a single column.

columns

height width

Remarks

OFFSET does not change the current selection in the worksheet. Because it returns a reference, OFFSET can be used in any function that requires or uses a cell or range reference as an argument.

Chapter 14 A-Z Worksheet Function Reference

261

Examples

This function returns the contents of cell D4:

OFFSET(B1, 3, 2, 1, 1)

This function returns the sum of the values in the range E3:F5:
SUM(OFFSET(A1, 2, 4, 3, 2))

OR
Description Syntax Returns True if at least one of a series of logical arguments is true. OR ( logical_list )
Parameter logical_list Description A list of conditions separated by commas. You can include as many as 30 conditions in the list. The list can contain logical values or a reference to a range containing logical values. Text and empty cells are ignored. If there are no logical values in the list, the error value #VALUE! is returned.

Example

This function returns True because one of the arguments is true:

OR(1 + 1 = 1, 5 + 5 = 10)

See Also

AND IF NOT

PI
Description Syntax Remarks Returns the value of pi (), which is approximately 3.14159265358979 when calculated to 15 significant digits. PI ( ) Although PI does not use arguments, you must supply the empty parentheses to correctly reference the function. COS SIN TAN

See Also

262

Formula One ActiveX Users Guide

PMT
Description Syntax Returns the periodic payment of an annuity, based on regular payments and a fixed periodic interest rate. PMT ( interest, nper, pv [, fv] [, type] )
Parameter interest nper pv fv type Description The fixed periodic interest rate. The number of periods in the annuity. The present value, or the amount the annuity is currently worth. The future value, or the amount the annuity will be worth. When you omit this argument, a future value of 0 is assumed. Indicates when payments are due. Use 0 if payments are due at the end of the period or 1 if payments are due at the beginning of the period. When you omit this argument, 0 is assumed.

Remarks

PMT returns only the principal and interest payment, it does not include taxes or other fees. The units used for interest must match those used for nper. For example, if the annuity has an 8 percent annual interest rate over a period of 5 years, specify 8 percent/12 for interest and 5*12 for nper. Cash paid out, such as a payment, is shown as a negative number. Cash received, such as a dividend check, is shown as a positive number.

Examples

This function returns 439.43:

PMT(8%/12, 48, 18000)

This function returns 436.52:

PMT(8%/12, 48, 18000, 0, 1)

See Also

IPMT FV NPER PPMT PV RATE

Chapter 14 A-Z Worksheet Function Reference

263

PPMT
Description Syntax Returns the principle paid on an annuity for a given period. PPMT ( interest, per, nper, pv, [fv], [type] )
Parameter interest per nper pv fv type Description The fixed periodic interest rate. The period for which to return the principle. The number of periods in the annuity. The present value, or the amount the annuity is currently worth. The future value, or the amount the annuity will be worth. When you omit this argument, a future value of 0 is assumed. Indicates when payments are due. Use 0 if payments are due at the end of the period or 1 if payments are due at the beginning of the period. When you omit this argument, 0 is assumed.

Remarks

The units used for interest must match those used for nper. For example, if the annuity has an 8 percent annual interest rate over a period of 5 years, specify 8 percent/12 for interest and 5*12 for nper. This function returns 321.56:
PPMT(8%/12, 2, 48, 18000)

Examples

This function returns 319.43:

PPMT(8%/12, 2, 48, 18000, 0, 1)

See Also

IPMT FV NPER PMT PPMT PV RATE

264

Formula One ActiveX Users Guide

PRODUCT
Description Syntax Multiplies a list of numbers and returns the result. PRODUCT ( number_list )
Parameter number_list Description A list of as many as 30 numbers, separated by commas. The list can contain numbers, logical values, text representations of numbers, or a reference to a range containing those values. Error values or text that cannot be translated into numbers return errors. If a range reference is included in the list, text, logical expressions, and empty cells in the range are ignored. All numeric values, including 0, are used in the calculation.

Example

This function returns 24:

PRODUCT(1, 2, 3, 4)

See Also

FACT SUM

PROPER
Description Syntax Returns the specified string in proper-case format. PROPER ( text )
Parameter text Description Any string.

Remarks

In proper-case format, the first alphabetic character in a word is capitalized. If an alphabetic character follows a number, punctuation mark, or space, it is capitalized. All other alphabetic characters are lowercase. Numbers are not changed by PROPER.

Chapter 14 A-Z Worksheet Function Reference

265

Examples

This function returns 3Rd Quarter:

PROPER("3rd Quarter")

This function returns John Doe:

PROPER("JOHN DOE")

See Also

LOWER UPPER

PV
Description Syntax Returns the present value of an annuity, considering a series of constant payments made over a regular payment period. PV ( interest, nper, pmt [, fv] [, type] )
Parameter interest nper pmt fv type Description The fixed periodic interest rate. The number of payment periods in the investment. The fixed payment made each period. The future value, or the amount the annuity will be worth. When you omit this argument, a future value of 0 is assumed. Indicates when payments are due. Use 0 if payments are due at the end of the period or 1 if payments are due at the beginning of the period. When you omit this argument, 0 is assumed.

Remarks

The units used for interest must match those used for nper. For example, if the annuity has an 8 percent annual interest rate over a period of 5 years, specify 8 percent/12 for interest and 5*12 for nper. Cash paid out, such as a payment, is shown as a negative number. Cash received, such as a dividend check, is shown as a positive number.

Examples

This function returns 17999.89:

PV(8%/12, 48, 439.43)

This function returns 17999.89:

PV(8%/12, 48, 439.43)

266

Formula One ActiveX Users Guide

See Also

FV IPMT NPER PMT PPMT RATE

RAND
Description Syntax Remarks Example Returns a number selected randomly from a uniform distribution greater than or equal to 0 and less than 1. RAND ( ) Although RAND does not use arguments, you must supply the empty parentheses to correctly reference the function. This function returns a random number greater than or equal to 0 and less than 10:.
RAND()*10

RATE
Description Syntax Returns the interest rate per period of an annuity, given a series of constant cash payments made over a regular payment period. RATE ( nper, pmt, pv [, fv] [, type] [, guess] )
Parameter nper pmt pv fv type Description The number of periods in the annuity. The fixed payment made each period. Generally, pmt includes only principle and interest, not taxes or other fees. The present value of the annuity. The future value, or the amount the annuity will be worth. When you omit this argument, a future value of 0 is assumed. Indicates when payments are due. Use 0 if payments are due at the end of the period or 1 if payments are due at the beginning of the period. When you omit this argument, 0 is assumed. Your estimate of the interest rate. If no argument is supplied, a value of 0.1 (10 percent) is assumed.

guess

Remarks

RATE is calculated iteratively, cycling through the calculation until the result is accurate to .00001 percent. If the result cannot be found after 20 iterations, #NUM! is returned. When this occurs, supply a different value for guess.

Chapter 14 A-Z Worksheet Function Reference

267

Example

The following example returns the monthly interest rate of .0067; the annual interest rate (.0067 multiplied by 12) is 8 percent:
RATE(48, 439.43, 18000)

See Also

FV IPMT NPER PMT PPMT PV

REGISTER.ID
Description Returns the register ID of the specified dynamic link library (DLL) that has been previously registered. If the DLL has not been registered, this function registers the DLL, and then returns the register ID. REGISTER.ID(module_text, procedure, type_text)
Parameter module_text procedure type_text Description The text specifying the name of the DLL that contains the function in Formula One. The text specifying the name of the function in the DLL in Formula One. The function name is case dependent in 32-bit Formula One. The text specifying the data type of the return value and the data types of all arguments to the DLL. The first letter of type_text specifies the return value. If the function or code resource is already registered, you can omit this argument. For a complete list of the data types available, see the type_text parameter of the CALL worksheet function.

Syntax

Remarks

For declarations made in C, it is assumed that your compiler defaults to 8-byte doubles, 2-byte short integers, and 4-byte long integers. In the Windows programming environment, all pointers should be far pointers. Pascal calling conventions are used for all functions called from DLLs. For most C compilers, you must add the Pascal keyword to the function declaration. If the return value for your custom function uses a pass-by-reference data type, a null pointer can be passed as the return value. The null pointer is interpreted as the #NUM! error value. For the F and G data types, a custom function can modify an allocated string buffer. If the return value type code is F or G, the value returned by the function is ignored. The list of function arguments is searched for the first data type that corresponds to the return value type. The current contents of the allocated string buffer is taken for the return value. 256 bytes is allocated for the argument; therefore, a function can return a larger string than it receives.

268

Formula One ActiveX Users Guide

You can use a single digit (n), with a value from 1 to 9, as the code for data_type. The variable in the location pointed to by the nth argument is modified instead of the return value; this process is referred to as modifying in place. The nth argument must be a pass-by-reference data type. In addition, you must declare the function void. For most C compilers, you can add the Void keyword to the function declaration. Examples The following formula registers the GetTickCount function with Formula One and returns the register ID:
REGISTER.ID("Kernel32", "GetTickCount", "J!")

Assuming that GetTickCount was already registered on another sheet using the preceding formula, the following formula returns the register ID for GetTickCount:
REGISTER.ID("Kernel32", "GetTickCount")

REPLACE
Description Syntax Replaces part of a text string with another text string. REPLACE ( orig_text, start_position, num_chars, repl_text )
Parameter orig_text start_position Description The original text string. The character position where the replacement begins. If start_position is greater than the number of characters in orig_text, repl_text is appended to the end of orig_text. If start_position is less than 1, #VALUE! is returned. num_chars repl_text The number of characters to replace. If this argument is negative, #VALUE! is returned. The replacement text string.

Examples

This function returns For the year: 1994:

REPLACE("For the year: 1993", 18, 1, "4")

See Also

MID SEARCH TRIM

Chapter 14 A-Z Worksheet Function Reference

269

REPLACEB
Description Syntax Replaces part of a text string with another text string. REPLACEB ( orig_text, start_position, num_bytes, repl_text )
Parameter orig_text start_position Description The original text string. The byte position where the replacement begins. If start_position is greater than the number of bytes in orig_text, repl_text is appended to the end of orig_text. If start_position is less than 1, #VALUE! is returned. num_bytes repl_text The number of bytes to replace. If this argument is negative, #VALUE! is returned. The replacement text string.

Remarks

REPLACEB is case-sensitive. You cannot use wildcard characters in the orig_text. start_position, num_bytes, and return value are expressed in bytes, so these values might differ on DBCS systems. On non-DBCS systems, these functions are identical, but REPLACEB should only be used in special applications that require distinctions between single-byte and double-byte characters.

Examples

This function returns For the year: 1994:

REPLACEB("For the year: 1993", 18, 1, "4")

REPT
Description Syntax Repeats a text string the specified number of times. REPT ( text, number )
Parameter text number Description Any text string. The number of times you want text to repeat. If number is 0, empty text ("") is returned.

Remarks Example

The result of REPT cannot exceed 255 characters. This function returns error-error-error-:
REPT("error-", 3)

270

Formula One ActiveX Users Guide

RIGHT
Description Syntax Returns the rightmost characters from the given text string. RIGHT ( text [, num_chars] )
Parameter text num_chars Description Any text string. The number of characters to return. The value must be greater than or equal to zero. If num_chars is greater than the number of characters in text, the entire string is returned. Omitting this argument assumes a value of 1.

Examples

This function returns r:

RIGHT("2nd Quarter")

This function returns Quarter:

RIGHT("2nd Quarter", 7)

See Also

LEFT MID

Chapter 14 A-Z Worksheet Function Reference

271

RIGHTB
Description Syntax Returns the rightmost bytes from the given text string. RIGHTB ( text [, num_chars] )
Parameter text num_bytes Description Any text string. The number of bytes to return. The value must be greater than or equal to zero. If num_bytes is greater than the number of bytes in text, the entire string is returned. Omitting this argument assumes a value of 1.

Remarks

num_bytes and return value are expressed in bytes, so these values might differ on DBCS systems. On non-DBCS systems, these functions are identical, but RIGHTB should only be used in special applications that require distinctions between singlebyte and double-byte characters. This function returns r:
RIGHTB("2nd Quarter")

Examples

This function returns Quarter:

RIGHTB("2nd Quarter", 7)

ROUND
Description Syntax Rounds the given number to the supplied number of decimal places. ROUND ( number, precision )
Parameter number precision Description Any value. The number of decimal places to which number is rounded. When a negative precision is used, the digits to the right of the decimal point are dropped and the absolute number of significant digits specified by precision are replaced with zeros. If precision is 0, number is rounded to the nearest integer.

Example

This function returns 123.46:

ROUND(123.456, 2)

This function returns 9900:

ROUND(9899.435, 2)

272

Formula One ActiveX Users Guide

See Also

CEILING FLOOR INT MOD ROUNDDOWN ROUNDUP TRUNC

ROUNDDOWN
Description Syntax Rounds a number down. ROUNDDOWN ( number, numberOfDigits)
Parameter number numberOfDigits Description Any real number you want to round. The number of decimal places to which number is rounded. When a negative precision is used, the digits to the right of the decimal point are dropped and the absolute number of significant digits specified by precision are replaced with zeros. If precision is 0, number is rounded down to the nearest integer.

Example

This function returns 31.141:

ROUNDDOWN(3.14159, 3)

This function returns 31.400:

ROUNDDOWN(31415.92654, -2)

See Also

CEILING FLOOR INT MOD ROUND ROUNDUP TRUNC

Chapter 14 A-Z Worksheet Function Reference

273

ROUNDUP
Description Syntax Rounds the given number up to the supplied number of decimal places. ROUNDUP ( number, numberOfDigits)
Parameter number numberOfDigits Description Any value you want to round up. The number of decimal places to which number is rounded. When a negative precision is used, the digits to the right of the decimal point are dropped and the absolute number of significant digits specified by precision are replaced with zeros. If precision is 0, number is rounded up to the nearest integer.

Example

This function returns 77:

ROUNDUP(76.9,0)

This function returns 3150:

ROUNDUP(31415.92654, -2)

See Also

CEILING FLOOR INT MOD ROUND ROUNDDOWN TRUNC

ROW
Description Syntax Returns the row number of the supplied reference. ROW ( reference )
Parameter reference Description A cell or range reference. Omitting this argument returns the row number of the cell in which ROW is entered.

Examples

This function returns 3:

ROW(B3)

See Also

COLUMN ROWS

274

Formula One ActiveX Users Guide

ROWS
Description Syntax Returns the number of rows in a range reference. ROWS ( range )
Parameter range Description A reference to a range of cells.

Examples

This function returns 5:

ROWS(A1:D5)

This function returns 6:

ROWS(C30:F35)

See Also

COLUMNS ROW

SEARCH
Description Syntax Locates the position of the first character of a specified text string within another text string. SEARCH ( search_text, text [, start_position] )
Parameter search_text Description The text to find. The search string can contain wildcard characters. The available wildcard characters are * (asterisk), which matches any sequence of characters, and ? (question mark), which matches any single character. To search for an asterisk or question mark, include a tilde (~) before the character. text start_position The text to be searched. The character position where the search begins. If the number you specify is less than 0 or greater than the number of characters in text, #VALUE! is returned. Omitting this argument assumes a starting position of 1.

Remarks Examples

Text is searched from left to right, starting at the position specified. The search is not case-sensitive. If text does not contain the search string, #VALUE! is returned. This function returns 6:

Chapter 14 A-Z Worksheet Function Reference

SEARCH("?5", "Bin b45")

275

This function returns 5:

SEARCH("b", "Bin b45", 4)

See Also

FIND MID REPLACE SUBSTITUTE

SEARCHB
Description Syntax Locates the position of the first byte of a specified text string within another text string. SEARCHB ( search_text, text [, start_position] )
Parameter search_text Description The text to find. To search for an asterisk or question mark, include a tilde (~) before the character. The search string can contain wildcards. The available wildcard characters are * (asterisk), which matches any sequence of characters, and ? (question mark), which matches any single character. text start_position The text to be searched. The character position where the search begins. If the number you specify is less than 0 or greater than the number of bytes in text, #VALUE! is returned. Omitting this argument assumes a starting position of 1.

Remarks

Text is searched from left to right, starting at the position specified. The search is not case-sensitive. If text does not contain the search string, #VALUE! is returned. start-position and return value are expressed in bytes, so these values might differ on DBCS systems. On non-DBCS systems, these functions are identical, but SEARCHB should only be used in special applications that require distinctions between single-byte and double-byte characters.

Examples

This function returns 6:

SEARCHB("?5", "Bin b45")

This function returns 5:

SEARCHB("b", "Bin b45", 4)

276

Formula One ActiveX Users Guide

SECOND
Description Syntax Returns the second that corresponds to the supplied date. SECOND ( serial_number )
Parameter serial_number Description The time as a serial number. The decimal portion of the number represents time as a fraction of the day.

Examples

This function returns 58:

SECOND(.259)

This function returns 46:

SECOND(34657.904)

See Also

DATE DAY HOUR MINUTE MONTH NOW TODAY WEEKDAY YEAR

SIGN
Description Syntax Determines the sign of the specified number. SIGN ( number )
Parameter number Description Any number.

Remarks Examples

SIGN returns 1 if the specified number is positive, 1 if it is negative, and 0 if it is 0. This function returns 1:
SIGN(123)

This function returns 1:

SIGN(123)

See Also

ABS

Chapter 14 A-Z Worksheet Function Reference

277

SIN
Description Syntax Returns the sine of the supplied angle. SIN ( number )
Parameter number Description The angle in radians. If the angle is in degrees, convert the angle to radians by multiplying the angle by PI( )/180.

Examples

This function returns .85:

SIN(45)

This function returns .89:

SIN(90)

See Also

ASIN PI

SINH
Description Syntax Returns the hyperbolic sine of the specified number. SINH ( number )
Parameter number Description Any number.

Examples

This function returns 1.18:

SINH(1)

This function returns 10.02:

SINH(3)

See Also

ASINH PI

278

Formula One ActiveX Users Guide

SLN
Description Syntax Returns the depreciation of an asset for a specific period of time using the straightline balance method. SLN ( cost, salvage, life )
Parameter cost salvage life Description The initial cost of the asset. The salvage value of the asset. The number of periods of the useful life of the asset.

Example

This function returns 1285.71:

SLN(10000, 1000, 7)

See Also

DDB SYD VDB

SQRT
Description Syntax Returns the square root of the specified number. SQRT ( number )
Parameter number Description Any positive number. If you specify a negative number, the error #NUM! is returned.

Examples

This function returns 3:

SQRT(9)

This function returns 1.58:

SQRT(2.5)

See Also

SUMSQ

Chapter 14 A-Z Worksheet Function Reference

279

STDEV
Description Returns the standard deviation of a population based on a sample of supplied values. The standard deviation of a population represents an average of deviations from the population mean within a list of values. STDEV ( number_list )
Parameter number_list Description A list of as many as 30 numbers, separated by commas. The list can contain numbers or a reference to a range that contains numbers.

Syntax

Example

This function returns .56:

STDEV(4.0, 3.0, 3.0, 3.5, 2.5, 4.0, 3.5)

See Also

STDEVP VAR VARP

STDEVP
Description Returns the standard deviation of a population based on an entire population of values. The standard deviation of a population represents an average of deviations from the population mean within a list of values. STDEVP ( number_list )
Parameter number_list Description A list of as many as 30 numbers, separated by commas. The list can contain numbers or a reference to a range that contains numbers.

Syntax

Example

This function returns .52:

STDEVP(4.0, 3.0, 3.0, 3.5, 2.5, 4.0, 3.5)

See Also

STDEV VAR VARP

280

Formula One ActiveX Users Guide

SUBSTITUTE
Description Syntax Replaces a specified part of a text string with another text string. SUBSTITUTE ( text, old_text, new_text [, instance] )
Parameter text old_text new_text instance Description A text string that contains the text to replace. You can also specify a reference to a cell that contains text. The text string to be replaced. The replacement text. Specifies the occurrence of old_text to replace. If this argument is omitted, every instance of old_text is replaced.

Examples

This function returns Second Quarter Results:

SUBSTITUTE("First Quarter Results", "First", "Second")

This function returns "Shipment 45, Bin 52":

SUBSTITUTE("Shipment 45, Bin 45", "45", "52", 2)

See Also

REPLACE TRIM

SUM
Description Syntax Returns the sum of the supplied numbers. SUM ( number_list )
Parameter number_list Description A list of as many as 30 numbers, separated by commas. The list can contain numbers, logical values, text representations of numbers, or a reference to a range containing those values. Error values or text that cannot be translated into numbers return errors. If a range reference is included in the list, text, logical expressions, and empty cells in the range are ignored.

Chapter 14 A-Z Worksheet Function Reference

281

Examples

This function returns 6000:

SUM(1000, 2000, 3000)

This function returns 4000 when each cell in the range contains 1000:
SUM(A10:D10)

See Also

AVERAGE COUNT COUNTA PRODUCT SUMSQ

SUMIF
Description Syntax Returns the sum of the specified cells based on the given criteria. SUMIF ( range, criteria, sum_range)
Parameter range criteria Description The range of cells you want evaluated. A number, expression, or text that defines which cells are added. For example, criteria can be expressed as 15, 15, >15, cars. The actual cells to sum. These cells are only summed if their corresponding cells in range match the criteria. If this argument is omitted, the cells in range are summed.

sum_range

See Also

AVERAGE COUNT COUNTA COUNTIF PRODUCT SUMSQ SUM

282

Formula One ActiveX Users Guide

SUMPRODUCT
Description Syntax Multiplies the corresponding cells in the given ranges, then returns the sum of those products. SUMPRODUCT (range_list)
Parameter Description

range_list

Two or more range references that provide the sets of numbers you want to multiply. The first cell in the first range is multiplied with the first cell in the second range. Then all the products are summed.

Remarks

All the ranges in range_list must contain the same number of cells in the same arrangement. That is, if the first range is three rows deep and three columns wide, the second and subsequent ranges must also be three rows deep and three columns wide. The following examples use this worksheet.

Examples

This formula returns 32:

SUMPRODUCT(A1:A3,B1:B3)

That is, 1 x 4 = 4 2 x 5 = 10 3 x 6 = 18 32 This formula returns 630:

SUMPRODUCT(A1:C1,A2:C2,A3:C3)

That is, 1 x 2 x 3 = 6 4 x 5 x 6 = 120 7 x 8 x 9 = 504 630 This formula returns 50:

SUMPRODUCT(A1:A3,C1:C3)

Chapter 14 A-Z Worksheet Function Reference

283

SUMSQ
Description Syntax Squares each of the supplied numbers and returns the sum of the squares. SUMSQ ( number_list )
Parameter number_list Description A list of as many as 30 numbers, separated by commas. The list can contain numbers, logical values, text representations of numbers, or a reference to a range containing those values. Error values or text that cannot be translated into numbers return errors. If a range reference is included in the list, text, logical expressions, and empty cells in the range are ignored.

Example

This function returns 302:

SUMSQ(9, 10, 11)

See Also

SUM

SYD
Description Returns the depreciation of an asset for a specified period using the sum-of-years method. This depreciation method uses an accelerated rate, where the greatest depreciation occurs early in the useful life of the asset. SYD ( cost, salvage, life, period )
Parameter cost salvage life period Description The initial cost of the asset. The salvage value of the asset. The number of periods in the useful life of the asset. The period for which to calculate the depreciation. The time units used to determine period and life must match.

Syntax

Example

This function returns 1607.14:

SYD(10000, 1000, 7, 3)

See Also

DDB SLN VDB

284

Formula One ActiveX Users Guide

T
Description Syntax Tests the supplied value and returns the value if it is text. T ( value )
Parameter value Description The value to test.

Remarks Examples

Empty text ( ) is returned for any value that is not text. This function returns Report:
T("Report")

This function returns empty text ( ) if A4 contains a number:

T(A4)

See Also

N VALUE

TAN
Description Syntax Returns the tangent of the specified angle. TAN ( number )
Parameter number Description The angle in radians. To convert a number expressed as degrees to radians, multiply the degrees by PI( )/180.

Examples

This function returns 0.752:

TAN(0.645)

This function returns 1:

TAN(45*PI()/180)

See Also

ATAN ATAN2 PI TANH

Chapter 14 A-Z Worksheet Function Reference

285

TANH
Description Syntax Returns the hyperbolic tangent of a number. TANH ( number )
Parameter number Description Any number.

Examples

This function returns .96:

TANH(2)

This function returns .83:

TANH(1.2)

See Also

ATANH COSH SINH TAN

TEXT
Description Syntax Returns the given number as text, using the specified formatting. TEXT ( number, format )
Parameter number format Description Any value, a formula that evaluates to a number, or a reference to a cell that contains a value. A string representing a number format. The string can be any valid format string including General, M/DD/YY, or H:MM AM/PM. The format must be surrounded by a set of double quotation marks. Asterisks cannot be included in format.

Examples

This function returns 123.620:

TEXT(123.62, "0.000")

This function returns 10/19/94:

TEXT(34626.2, "MM/DD/YY")

286

Formula One ActiveX Users Guide

See Also

DOLLAR FIXED T VALUE

TIME
Description Syntax Returns a serial number for the supplied time. TIME ( hour, minute, second )
Parameter hour minute second Description A number from 0 to 23. A number from 0 to 59. A number from 0 to 59.

Examples

This function returns .52:

TIME(12, 26, 24)

This function returns .07:

TIME(1, 43, 34)

See Also

HOUR MINUTE NOW SECOND TIMEVALUE

TIMEVALUE
Description Syntax Returns a serial number for the supplied text representation of time. TIMEVALUE ( text )
Parameter text Description A time in text format.

Examples

This function returns .07:

TIMEVALUE("1:43:43 am")

Chapter 14 A-Z Worksheet Function Reference

287

This function returns .59:

TIMEVALUE("14:10:07")

See Also

HOUR MINUTE NOW SECOND TIME

TODAY
Description Syntax Remarks See Also Returns the current date as a serial number. TODAY ( ) This function is updated only when the worksheet is recalculated. DATE DAY NOW

TRIM
Description Syntax Removes all spaces from text except single spaces between words. TRIM ( text )
Parameter text Description Any text string or a reference to a cell that contains a text string.

Remarks Example

Text that is imported from another environment may require this function. This function returns Level 3, Gate 45:
TRIM(" Level 3, Gate 45 ")

See Also

CLEAN MID REPLACE SUBSTITUTE

288

Formula One ActiveX Users Guide

TRUE
Description Syntax See Also Returns the logical value True. This function always requires the trailing parentheses. TRUE ( ) FALSE

TRUNC
Description Syntax Truncates the given number to an integer. TRUNC ( number [, precision] )
Parameter number precision Description Any value. The number of decimal places allowed in the truncated number. Omitting this argument assumes a precision of 0.

Remarks Examples

TRUNC removes the fractional part of a number to the specified precision without rounding the number. This function returns 123.45:
TRUNC(123.456, 2)

This function returns 9800:

TRUNC(9899.435, 2)

See Also

CEILING FLOOR INT MOD ROUND

Chapter 14 A-Z Worksheet Function Reference

289

TYPE
Description Syntax Returns the argument type of the given expression. TYPE ( expression )
Parameter expression Description Any expression.

Remarks

The valid values returned by this argument are:

Number 1 2 4 16 Description Number Text string Logical value Error value

Examples

This function returns 1 if cell A1 contains a number:

TYPE(A1)

This function returns 2:

TYPE("Customer")

See Also

ISBLANK ISERR ISERROR ISLOGICAL ISNA ISNONTEXT ISNUMBER ISREF ISTEXT

UPPER
Description Syntax Changes the characters in the specified string to uppercase characters. UPPER ( text )
Parameter text Description Any string.

290

Formula One ActiveX Users Guide

Remarks Examples

Numeric characters in the string are not changed. This function returns 3RD QUARTER:
UPPER("3rd Quarter")

This function returns JOHN DOE:

UPPER("JOHN DOE")

See Also

LOWER PROPER

USDOLLAR
Description Syntax Returns the specified number as text using the US Dollar format and the supplied precision. Omitting the precision argument assumes two decimal places. USDOLLAR ( number [, precision] )
Parameter number precision Description A number, a formula that evaluates to a number, or a reference to a cell that contains a number. A value representing the number of decimal places to the right of the decimal point. Omitting this argument assumes two decimal places.

Examples

This function returns $1023.79:

USDOLLAR(1023.789)

This function returns $500:

USDOLLAR(495.301, 2)

See Also

FIXED TEXT VALUE DOLLAR

Chapter 14 A-Z Worksheet Function Reference

291

VALUE
Description Syntax Returns the specified text as a number. VALUE ( text )
Parameter text Description Any text string, a formula that evaluates to a text string, or a cell reference that contains a text string. You can also specify a date or time in a recognizable format (for example, M/DD/YY for dates or H:MM AM/PM for time). If the format is not recognized, #VALUE! is returned.

Examples

This function returns 9800:

VALUE(9800)

This function returns 123:

VALUE("123")

See Also

DOLLAR FIXED TEXT

VAR
Description Syntax Returns the variance of a population based on a sample of values. VAR ( number_list )
Parameter number_list Description A list of as many as 30 numbers, separated by commas. The list can contain numbers or a reference to a range that contains numbers.

Example

This function returns .31:

VAR(4.0, 3.0, 3.0, 3.5, 2.5, 4.0, 3.5)

See Also

STDEV STDEVP VARP

292

Formula One ActiveX Users Guide

VARP
Description Syntax Returns the variance of a population based on an entire population of values. VARP ( number_list )
Parameter number_list Description A list of as many as 30 numbers, separated by commas. The list can contain numbers or a reference to a range that contains numbers.

Example

This function returns .27:

VARP(4.0, 3.0, 3.0, 3.5, 2.5, 4.0, 3.5)

See Also

STDEV STDEVP VAR

VDB
Description Syntax Returns the depreciation of an asset for a specified period using a variable method of depreciation. VDB ( cost, salvage, life, start_period, end_period [, factor] [, method] )
Parameter cost salvage life start_period end_period factor Description The initial cost of the asset. The salvage value of the asset. The number of periods in the useful life of the asset. The beginning period for which to calculate the depreciation. The time units used to determine start_period and life must match. The ending period for which to calculate the depreciation. The time units used to determine end_period and life must match. The rate at which the balance declines. Omitting this argument assumes a default of 2, which is the double-declining balance factor. A logical value that determines if you want to switch to straight-line depreciation when depreciation is greater than the declining balance calculation. Use True to maintain declining balance calculation; use False or omit the argument to switch to straight-line depreciation calculation.

method

Chapter 14 A-Z Worksheet Function Reference

293

Example

This function returns 1041.23:

VDB(10000, 1000, 7, 3, 4)

See Also

DDB SLN SYD

VLOOKUP
Description Syntax Searches the first column of a table for a value and returns the contents of a cell in that table that corresponds to the location of the search value. VLOOKUP ( search_item, search_range, column_index )
Parameter search_item search_range Description A value, text string, or reference to a cell containing a value that is matched against data in the top row of search_range. The reference of the range (table) to be searched. The cells in the first column of search_range can contain numbers, text, or logical values. The contents of the first column must be in ascending order (for example, 2, 1, 0, 2...A through Z, False, True). Text searches are not case-sensitive. The column in the search range from which the matching value is returned. column_index can be a number from 1 to the number of rows in the search range. If column_index is less than 1, #VALUE! is returned. When column_index is greater than the number of rows in the table, #REF! is returned.

column_index

Remarks

VLOOKUP compares the information in the first column of search_range to the supplied search_item. When a match is found, information located in the same row and supplied column (column _index) is returned. If search_item cannot be found in the first column of search_range, the largest value that is less than search_item is used. When search_item is less than the smallest value in the first column of the search_range, #REF! is returned.

294

Formula One ActiveX Users Guide

Examples

The following examples use this worksheet.

This function returns $28,700:

VLOOKUP("Clark", A2:E9, 4)

This function returns 3961:

VLOOKUP("Lee", A2:E9, 3)

See Also

HLOOKUP INDEX LOOKUP MATCH

WEEKDAY
Description Syntax Returns the day of the week that corresponds to the supplied date. WEEKDAY ( serial_number )
Parameter serial_number Description The date as a serial number or as text (for example, 06-21-94 or 21-Jun-94).

Remarks Examples

WEEKDAY returns a number ranging from 1 (Sunday) to 7 (Saturday). This function returns 1, indicating Sunday:
WEEKDAY(34399.92)

This function returns 3, indicating Tuesday:

WEEKDAY("06/21/94")

Chapter 14 A-Z Worksheet Function Reference

295

See Also

DAY NOW TEXT TODAY

YEAR
Description Syntax Returns the year that corresponds to the supplied date. YEAR ( serial_number )
Parameter serial_number Description The date as a serial number or as text (for example, 06-21-94 or 21-Jun-94).

Examples

This function returns 1993:

YEAR(34328)

This function returns 1994:

YEAR("06/21/94")

See Also

DAY NOW HOUR MINUTE MONTH SECOND TODAY WEEKDAY

Tidestone

297

Index
A
About box displaying every 30 minutes xi, xii viewing xii AboutBox method xii ABS function 203 Absolute cell references 70 ACOS function 203 ACOSH function 204 Active cell 57, 58, 60 worksheet 50, 59 ActiveX Add-Ins in Visual Basic 183188 controls, adding to your application 1 AddColPageBreak method 153 Add-In functions creating 183 formula evaluation errors, chart 198 requirements for 184 AddPageBreak method 153 ADDRESS function 205 AddRowPageBreak method 153 AddSelection method 61 AlignHorizontal property 108 Aligning data 107108 Center toolbar button 43 Left Align toolbar button 43 Merge and Center toolbar button 43 Right Align toolbar button 43 SetAlignment method 52 AlignVertical property 108 Allocating memory 179 AllowArrows property 86 AllowCellTextDlg property 81, 86 AllowDelete property 58, 81, 86 AllowDesigner property 37 AllowEditHeaders property 81, 82, 121 AllowFillRange property 81, 86 AllowFormulas property 81, 85 AllowInCellEditing property 81 AllowMoveRange property 81, 86 AllowObjSelections property 62, 129, 146 AllowResize property 81, 86, 113 AllowSelections property 62 AllowTabs property 86 Anchors in HTML files 171 AND function 206 Arc command (Insert menu) 40 Arcs creating 123125 tool for 125 Area references as arguments 185 Arguments 2D area reference 192 2D, 3D, and union 192 and return values 191 in functions 73, 74 Arithmetic operators 68 Array arguments in functions 183 #ARRAY_FORMULA! error 72 Arrow keys 58, 85 ASIN function 206 ASINH function 207 ATAN function 208 ATAN2 function 208 ATANH function 209 Attach method 27, 30 AttachToSS method 27, 30 Autofill lists 74 adding 75 deleting 76 dragging for filling 88 AutoFillItems property 75, 76 AutoFillItemsCount method 75 Automatic recalculation 77 AutoPageNumber property 155 AutoRecalc property 77, 78 AVERAGE function 209 Axes page, in Chart Wizard 144

B
Background color, for graphical objects 133 Bar gap, on charts 143 Binding worksheet columns 169 Black and white printing 159 BlackAndWhite property 159 BLOBs reading and writing workbooks as 33 using multiple versions of Formula One and 33 Bold toobar button 43 Boolean 184 BorderColor property 117

298

Formula One ActiveX Users Guide

Cells (continued) preventing selection of 62 programatically clearing 98 selecting 6061 selecting with properties and methods 61 selecting with the keyboard 5859 selecting with the mouse 60 type markers 46 Cells command (Format menu) 40, 81, 83, 99, 102, 107, 108, 109, 117, 118 Cells command (Insert menu) 39 Center Across toolbar button 43 Center toolbar button 43 CenterHoriz property 154 CenterVert property 154 CFormView-based applications, in Visual C++ 23 adding Formula One to 45 CHAR function 213 Chart command (Insert menu) 39, 141 Chart Designer 145 Chart Wizard 142146 labeling chart axes in 144 modifying existing charts with 144 navigating in 142 selecting chart types in 143 selecting styles in 143 setting chart elements in 144 Charts 141147 changing chart data 145 creating 123125, 142147 data range for 146 data requirements for different types 142 formatting with the Chart Designer 145 modifying data 145 modifying, with the Chart Wizard 144 referencing data on a different worksheet 147 selecting styles 143 selecting types 143 tool for 125 Check boxes creating 123125 formatting 136 input value cells for 138 selection values for 137139 tool for 125 Checkbox command (Insert menu) 40 CHOOSE function 214 Circles. See Ovals Circular references, calculating 79 CLEAN function 215 Clear All command (Edit menu) 38 Clear Contents command (Edit menu) 38 Clear Formats command (Edit menu) 38

Borders on cells 116118 on graphical objects 134135 BorderStyle property 117 BottomMargin property 154 Bring to Front command (Format menu) 41, 132 Built-in formats 99100 functions 7274 Button command (Insert menu) 40 Buttons creating 123125 formatting 137 tool for 125 ByVal 183

C
C++ Add-In API 189198 Calculating workbooks 7779 automatically 77 circular references when 79 CALL function 78 Cancel Insert Object command (Insert menu) 40 Cancelling data entry or editing 58 CEILING function 212 Cell reference in formula bar 46, 64 Cell references 6971 as function arguments 74 automatically entering 71 for check boxes 138 for dropdown list boxes 135, 138 in formulas 6971 in validation rules 82 of merged cells 109 to other workbooks 71 to other worksheets 70 with named row and column headings 121 Cells active 57, 58, 60 aligning data in 107108 attributes of 87 borders on 116118 clearing 97 deleting 98 displaying data types, with type markers 46 formatting to optimize memory 177 inserting 96 limiting number displayed on a worksheet 5556 locking 8182 merged 109110 naming 76 preventing resizing of 86

Index
ClearClipboard method 92 Clearing, cells 97 ClearRange method 52, 98 Clipboard, pasting from, with methods 92 Close command (File menu) 37 CODE function 215 Col property (F1FindReplaceInfo object) 95 ColHeadings property 159 ColHidden property 113 Colon (:), in range references 69 Color palette 48 Color toolbar button 43 Colors defining, in color palette 48 for borders of graphical objects 134 for cell borders 117 for cell data 107 for filling cells 118119 for graphical objects 133134 in number formats 105 maximum number, per workbook 180 printing as shades of gray 159 ColText property 52, 121 Column Autofit Selection command (Format menu) 40 Column Default Width command (Format menu) 41 COLUMN function 216 Column headings formatting 119 hiding 56 preventing changes to 82 preventing resizing of 86 printing 159 selecting 119 sizing 120 text of 120121 Column Hide command (Format menu) 40 Column Unhide command (Format menu) 41 Column width affected by default font 46 affected by displaying formulas 56 Column Width command (Format menu) 40 Columns applying number formats 101 building to optimize memory 177 deleting 98 freezing 116 headings (see column headings) inserting 96 maximum width 180 preventing selection of 62 print titles and 151 selecting 61 setting widths of 110114

299

Columns (continued) automatically 113 default 111 Columns command (Insert menu) 39 COLUMNS function 78, 216 ColWidth property 52, 113 ColWidthDlg method 52, 113 ColWidthTwips property 113 ColWidthUnits property 46, 114 Commas in cell references 70 in functions 73 Common Fixed and General Formats toolbar button 43 Comparison operators 68 CONCATENATE function 217 Conditional values, in number formats 105 Connect string 163 Constant values entering 6667 naming 76 using to optimize memory 177 Constants, not read in Visual C++ 2 Context menu 57 Converting from previous versions of Formula One 20 Copy Cell Format command (Edit menu) 38 Copy command (Edit menu) 38 Copy Format toolbar button 42 Copy toolbar button 42 CopyAll method 92 CopyDataFromArray method 93 CopyDataToArray method 93 Copying cell references 92 data across ranges 93 and optimizing performance 178 by dragging 57, 88 with drag-and-drop 88 with menu commands 91 with methods 92, 93 formulas 92 CopyRange method 52, 93, 178 CopyRangeEx method 7, 93, 178 COS function 217 COSH function 218 COUNT function 218 COUNTA function 219 COUNTIF function 220 CreateNewCellFormat method 117 Currency toolbar button 43 Currency, formatting numbers as 100 Custom data formats 102106 Cut command (Edit menu) 38

300

Formula One ActiveX Users Guide

DATEVALUE function 221 DAY function 221 Days of the week, automatically entering names of 74 DB function 223 DDB function 223 Declaring Add-In Functions in C++ 189 Default Font command (Format menu) 41 Default Height command (Format menu) 111 Default Width command (Format menu) 111 Defaults column width 111 font 46 for data alignment 107 for locking cells 82 number format 99 row height 111 workbook display options 4548 worksheet display options 5556 DefColWidthDlg method 52 DefinedName property 76 DefineSearch method ix, 95 DefRowHeightDlg method 52 Delete command (Edit menu) 39 Delete Sheet command (Edit menu) 39, 54 DeleteAutofillItems method 76 DeleteDlg method 52 DeleteRange method 52, 98 DeleteSheets method 54 Deleting autofill lists 76 cells 97, 98 columns 98 page breaks 152153 ranges 98 rows 98 worksheets 54 Development environments, for Formula One 1 Dialog-based applications, in Visual C++ 23 adding Formula One to 45 Disconnecting from databases 170 Displaying cell reference in formula bar 46, 64 cells on a worksheet 5556 data types, with type markers 46 formula bar 46, 64 formulas 72 parts of the workbook 4548 parts of worksheets 5556 type markers 46 worksheet tabs 46 zero values 56 #DIV/0! error 72 Docking the toolbars 37

Cut toolbar button 42 Cutting cell references 92 data and optimizing performance 178 with menu commands 91 with methods 92, 93 formulas 92 CView-based applications, in Visual C++ 23 adding Formula One to 56

D
Data aligning 107108 clearing 98 filling worksheets with, and optimizing memory 179 formatting 99108 built-in formats for 99100 custom formats for 102106 inserting or updating in databases 167 ranges of (see ranges) retrieving from database 161170 sorting 98 types of 66 validating 82 Data entry 6365 constant values and 6667 formulas and 6772 limiting 8086 multi-line 65 properties for 64 with check boxes and dropdown list boxes 137 Data Grid Editor 145 Data structure 178 Data types, displaying with type markers 46 Databases 161170 binding worksheet columns in 169 connecting to 161, 162 disconnecting from 170 installing ODBC drivers for 161 PREPARE statements for 168, 170 querying 164 setting up 162 workbooks in 33 DataTransferRange property 93 Date and Time toolbar button 44 DATE function 220 Dates entering 67 formatting numbers as 101, 104 printing, in headers and footers 157 range of, accepted by Formula One x

Index
Documentation conventions xiii DOLLAR function 224 Dollar sign ($), in cell references 70 DoSafeEvents property 175 Double 184 Drag-and-drop copying data using 88 copying from other applications using 90 moving data using 88 Dragging copying using 88 filling from autofill lists using 88 preventing users from 86 Drawing and Forms Toolbar command (View menu) 39 Drawing toolbar 36 Drawing, graphical objects interactively 124 Drivers, ODBC 161 Dropdown List box command (Insert menu) 40 Dropdown list boxes creating 123125 formatting 135 input value cells for 138 items in 136 numbering scheme for items 137 selection values for 137139 tool for 125 Equal sign (=) in formulas 67 in functions 73 Error values, default alignment of 107 ERROR.TYPE function 225 Errors entering 67 function syntax 74 trapping, in PowerBuilder 20 worksheet formula 72 Escape key 58 EVEN function 226 Events, Formula One, in Visual C++ 7 EXACT function 227 Excel 4.x file format 32, 37 features ignored in Formula One 32 graphical objects 123 password-protected files 32 reading and writing files 32 validation rules 83 Exclamation mark (!), in sheet references 70 Executing PREPARE statements 170 Exit command (File menu) 38 EXP function 227 External references 71

301

E
Edge of worksheet, moving the active cell to 59 Edit menu, in Workbook Designer 38 Edit mode 58 See also In-cell editing EditClear method 52, 98 EditCopy method 92 EditCopyDown method 93, 178 EditCopyRight method 93, 178 EditCut method 92 EditDelete method 52, 98 EditDeleteSheets method 54 EditInsert method 52, 96, 98 EditInsertSheets method 53 EditPaste method 92 EditPasteValues method 92 Embedding Data in HTML files 171 EnableProtection property 52, 81 EndCol property 131 EndRow property 131 EnterMovesDown property 58, 86 Entry property 52, 64, 83 EntryRC property 52, 64, 83 EntrySRC property 52

F
F1AddInArray 184, 185 F1AddInArrayEx 184, 185 F1AddInInit 190 F1AddInRegisterFunctionProc 191 F1AddInRegisterInfoProc 190 F1Book API object 23 guidelines for using 30 understanding the 2627 F1BookView API object 23 guidelines for using 30 properties and methods that cannot be used with 29 understanding the 2730 F1CellFormat API object 24, 116, 117 F1EventArg API object 24 F1FileSpec API object 24 F1FindReplaceInfo API object 23 F1Functions 183 F1NumberFormat API object 24 F1ObjPos API object 24, 131 F1ODBCConnect API object 24, 162 F1ODBCQuery API object 24, 164 F1PateSetup API object 24 F1RangeRef API object 24, 61 F1Rect API object 24

302

Formula One ActiveX Users Guide

FormatFontDlg method 52 FormatNumberDlg method 52 FormatObjectDlg method 128, 134, 135, 136 FormatPaintMode property 38 FormatPatternDlg method 52 FormatSheetDlg method 52 FormattedText property 101 FormattedTextRC property 101 FormattedTextSRC property 101 Formatting cell borders 116118 cells, to optimize memory 177 column widths 110114 programmatically 114 data 99108 fonts 106107 graphical objects 133137 row and column headings 119 row heights 110114 programmatically 114 with built-in data formats 99100 with custom data formats 102106 Formatting toolbar 36, 43 Formula bar 36 displaying 46, 64, 80 Formula Bar command (View menu) 39, 64 Formula evaluation errors 198 Formula One 1.x file format 32 2.x file format 20, 32, 37 adding the component to PowerBuilder 1213, 16, 19 adding the component to Visual Basic 89 adding the component to Visual C++ 36 data structure of 178 documentation conventions of xiii features ignored in Excel 32 installation of xxii new features of ix objects 2324 technical support of xii trial version of x, xii upgrading from previous versions 20 using multiple versions of 21, 33 Formula property 52, 65, 67 FormulaLocal property 52 FormulaLocalRC property 52 FormulaLocalSRC property 52 FormulaRC property 52, 65, 67 Formulas cell references in 6971 copying data and 92 cutting data and 92 displaying 56, 72

F1ReplaceResults API object 24 FACT function 228 FALSE function 228 File menu, in Workbook Designer 37 FilePageSetupDlg method 52, 149 FilePageSetupDlgEx method 52 FilePrint method 149 FilePrintEx method 7, 150 FilePrintPreview method 160 FilePrintSetupDlg method 150 Fill command (Edit menu) 38 Filling preventing users from, with mouse 86 ranges 74 worksheets with data, and optimizing memory 179 Find and replace 94 using properties and methods 95 using the Workbook Designer 94 Find command (Edit menu) 39 Find dialog box 94 FIND function 228 FINDB function 229 FindDlg method 95 FindNext method x, 95 First Impression ActiveX control 141147, 161 Chart Designer 145 Data Grid Editor 145 using to draw charts 125, 141 FirstPageNumber property 155 FitPages property 158 FIXED function 230 FixedCol property 116 FixedRow property 116 Fixing rows and columns. See Freezing panes FLOOR function 230 Fonts changing default 46 default affects column width 46 formatting 106107 Formula Ones default 47 maximum number, per workbook 180 scripts in 47, 107 FooterMargin property 154 Footers formatting codes for 156157 margins for 154 printing 156157 Footnotes, for charts 144 Foreground color, for graphical objects 133 Format menu, in Workbook Designer 40 FormatAlignmentDlg method 52 FormatBorderDlg method 52 FormatCellsDlg method 52, 84, 102, 108, 118, 119

Index
Formulas (continued) entering 6772 errors in 72 external cell references in 71 functions and 7274 limiting entry of 85 maximum length 180 naming 76 operators in 68 operators precedence in 69 FormulaSRC property 52, 67 Fraction toolbar button 44 Fractions, formatting numbers as x, 100 Freeing memory 179 Freeze Panes command (Format menu) 41, 115, 116 Freezing panes 115116 example of 115 programmatically 116 Functions 7274, 203295 arguments for 74 cell references in 74 entering 73 maximum number of arguments 180 nesting 73 syntax errors in 74 using array arguments in 183 FV function 231 Graphical objects (continued) selection values for 137139 sizing 130132 using mouse mode when creating 126 Grid lines aligning graphical objects to 125, 130 hiding 56 printing 159 GridLines property 159

303

H
HAlign property 52 HdrHeight property 52, 120 HdrWidth property 52, 120 HeaderMargin property 154 Headers formatting codes for 156157 margins for 154 printing 156157 row and column (see row headings, column headings) Headings, creating using merged cells 109 Height command (Format menu) 112 Hiding calculations 27 column headings 56 graphical objects 135 grid lines 56 row headings 56 type markers 46 worksheet tabs 31, 46 zero values 56 HLOOKUP function 232 HOUR function 233 HTML 171 anchors 171 reading and writing file types 32 source files 171 writing a range to an HTML file 34

G
Gallery page, in Chart Wizard 143 GetArrayType 185 GetCellFormat method 81 GetIteration method 79 Goto command (Edit menu) 39 Graphical objects arranging layers of 132133 borders 134135 creating 123125 drawing interactively 124 editing polygons 139140 fill colors and patterns 133134 formatting 133137 hiding 135 identifying 126 input value cells for 138 moving 130132 naming 128 not supported in Excel 123 preventing selection of 62, 129 repositioning 57 resizing 57 selecting 128130

I
IDataObject 93 Identifying graphical objects by number 126 IF function 234 Images, importing 125 Import command (File menu) 37 In-cell editing 57 disabling 85 in-cell edit space x See also Edit mode INDEX function 78, 234

304

Formula One ActiveX Users Guide

Index list of worksheets 50, 53, 71 Index numbers, of worksheets 31 INDIRECT function 78, 235 Insert menu, in Workbook Designer 39 InsertDlg method 52 InsertHTML method 34, 172 Inserting cells 96 columns 96 database data 167 rows 96 worksheets 49, 52 InsertRange method 52, 96 InsertSheets method 53 Installing, Formula One xxii Instancing property 183 INSTPROB.DOC file xii INT function 236 IntelliPoint mouse 57 Internet development events for 174 methods for 174 performing 173175 Intranet development events for 174 methods for 174 performing 173175 Invisible workbooks attaching 30 See also F1BookView API object IObjectSafety interface 171, 174 IPMT function 236 IRR function 237 ISBLANK function 238 ISERR function 239 ISERROR function 239 ISLOGICAL function 240 ISNA function 240 ISNONTEXT function 241 ISNUMBER function 242 ISREF function 242 ISTEXT function 243 Italic toolbar button 43 Items, in dropdown list boxes 136 IterationEnabled property 79 IterationMax property 79 IterationMaxChange property 79 Iterations circular references and 79 maximum number allowed in worksheet 180 IterNext and IterStart 185 IterStart and IterNext 185

K
Keyboard commands 58 limiting user access to 85 Keywords, in functions 73

L
Landscape printing orientation 157 LaunchDesigner method 36 Launching the Workbook Designer 36 Layout page, in Chart Wizard 144 Left Align toolbar button 43 LEFT function 243 LEFTB function 244 LeftMargin property 154 Left-to-right printing 158 LeftToRight property 158 Legends, for charts 144 LEN function 244 LENB function 245 Limiting data entry 8086 Line command (Insert menu) 40 Line feeds, cell entries and 65 LineColor property 135 Lines as borders on graphical objects 134135 creating 123125 formatting 134135 styles 134 tool for 124 LineStyle property 135 LineWeight property 135 List boxes. See Dropdown list boxes List, in dropdown list box 135 LN function 245 Locking cells 8182 displaying message 82 LOG function 246 LOG10 function 246 Logical property 52, 65 Logical values default alignment of 107 entering 67 LogicalRC property 52, 65 LogicalSRC property 52 LOOKUP function 247 LOWER function 248

Index

305

M
Main toolbar 36 Margins 154 MATCH function 249 MAX function 250 MaxCol property 31, 56 MaxRow property 31, 56 Member variables, in Visual C++ 45 Memory allocating 179 freeing 179 optimizing use of 177180 Menus, in Workbook Designer 3741 Merge and Center toolbar button 43 MergeCells property 109 Merging cells 109110 MID function 251 MIDB function 252 MIN function 253 MinCol property 31 Minimal recalcuation 78 MinimalRecalc property 79 MinRow property 31 MINUTE function 253 MIRR function 254 MOD function 255 Mode property 126 MONTH function 255 Months, automatically entering names of 74 Mouse actions of 57 drawing graphical objects 125 IntelliPoint mouse x limiting access to certain actions 86 selecting graphical objects 129 setting mode of 126 with checkboxes and dropdown list boxes 138 MoveRange method 52, 93, 178 Moving active cell 58 data and optimizing performance 178 with drag-and drop 88 with dragging 57 with menu commands 91 with methods 92, 93 graphical objects 130132 worksheet tabs 46 Multi-line data entry 58, 65, 108 preventing 85

N
N function 256 #N/A error 72 NA function 256 Name command (Insert menu) 40, 76 #NAME? error 72 Names built-in 77 cell 76 column heading 57 constant value 76 defining 76 formula 76 graphical object 128 maximum length 180 maximum number, per workbook 180 range 76 row heading 57 top left corner 57 worksheet 55, 57 worksheet and workbook, in headers and footers 157 Navigating in worksheets 5659 with keyboard commands 58 with mouse actions 57 with properties and methods 61 Nesting functions 73 New command (File menu) 37 New toolbar button 42 NextColPageBreak method 153 NextRowPageBreak method 153 NOT function 257 NOW function 78, 257 NPER function 258 NPV function 259 #NULL! error 72 #NUM! error 72 Number property 52, 65 NumberFormat property 52, 102 NumberFormatLocal property 52 Numbering, pages 155 NumberRC property 52, 65 Numbers as currency 100 as dates 101 as entries 66 as fractions 100 as percentages 103 as percents 100 as times 101 in scientific notation 100, 103 NumberSRC property 52 NumSheets property 53, 54

306

Formula One ActiveX Users Guide

ODBC (continued) connecting to the data source 162 drivers 161 PREPARE statements 168, 170 setting up the data source 162 ODBCBindParameter method 167, 169, 170 ODBCBindParameterEx method 167, 169, 170 ODBCConnect method 162, 167 ODBCConnectEx method 162, 167 ODBCDisconnect method 170 ODBCError method 167, 170 ODBCErrorMsg property 167, 170 ODBCExecute method 167, 170 ODBCExecuteError event 168, 170 ODBCExecuteEx method 167, 170 ODBCNativeError property 167, 170 ODBCPrepare method 167, 168, 169, 170 ODBCPrepareEx method 167, 168, 169, 170 ODBCQuery method 164, 168 ODBCQueryEx method 164, 168 ODBCSQLState property 168, 170 ODD function 259 OFFSET function 78, 260 Open command (File menu) 37 Operators formula 68 precedence of 69 Optimizing Formula One 177180 Options command (Tools menu) 41, 78, 79 OptionsDlg method 75, 77, 79 OR function 261 Oval command (Insert menu) 40 Ovals creating 123125 tool for 124 Overlapping graphical objects 132133

O
ObjAddItem method 136 ObjAddSelection method 129 ObjBringToFront method 127, 128, 132 ObjCellCol property 139 ObjCellRow property 139 ObjCellType property 139 ObjClick event 128, 129 ObjCreate method 123, 124 ObjCreatePicture method 124, 126 ObjDblClick event 128, 129 ObjDeleteItem method 136 Object command (Format menu) 41, 127, 128, 133, 134, 136, 137, 139, 146, 147 Objects Formula One 2324 in Visual C++ 6 graphical (see graphical objects) ObjFirstID method 127 ObjGetCell method 139 ObjGetItemCount method 136 ObjGetPos method 131, 132 ObjGetSelection method 127, 129 ObjGetSelectionCount method 130 ObjGotFocus event 128 ObjInsertItem method 136 ObjItem property 136 ObjItems property 136 ObjLostFocus event 128 ObjName property 128 ObjNameToID method 127 ObjNew method 123, 124, 141 ObjNewPicture method 124, 126 ObjNextID method 127 ObjPatternBG property 128, 133 ObjPatternFG property 128, 133 ObjPatternStyle property 128, 133 ObjPosToTwips method 132 ObjPosToTwipsEx method 132 ObjSelection property 130 ObjSendToBack method 127, 128, 132 ObjSetCell method 139 ObjSetPicture method 126 ObjSetPos method 131 ObjSetSelection method 129 ObjText property 137, 138 ObjValue property 138 ObjValueChanged event 128 ObjVisible property 135 ODBC 161170 binding of worksheet columns 169 configuring, in PowerBuilder 10

P
Page Break command (Insert menu) 40, 152 Page breaks, setting and removing 152153 Page numbers 155 in headers and footers 157 Page Setup command (File menu) 38, 151, 152, 154, 155, 156, 157, 158 PagesTall property 158 PagesWide property 158 PaletteEntry property 48 Paper size 158 PaperSize property 158 Parameters passed by reference, in PowerBuilder 20 Parentheses, in functions 73 Paste command (Edit menu) 38

Index
Paste Special command (Edit menu) 38 with merged cells 110 Paste toolbar button 42 Pasting data, with methods 92 merged cells 109 Patterns for filling cells 118119 for graphical objects 133134 Percent toolbar button 44 Percentages, formatting numbers as 103 Percents, formatting numbers as 100 PI function 261 Picture objects 124, 125 PMT function 262 Point, as measure for line weight 134 PolyEditMode property 139 Polygon command (Insert menu) 40 Polygon point editing 124, 139 Polygon Points command (Edit menu) 38 Polygons editing 139140 tool for 125 tool for edit mode 124 Portrait printing orientation 157 PowerBuilder 920 and application templates 11 and Formula One, web page 9 and ODBC 10 errors in 20 syntax 19 tutorials for Formula One 1018 working in 1920 working with databases in 1011, ??14 PPMT function 263 PREPARE statements 168, 170 Print area 77 Print Area command (File menu) 38 Print command (File menu) 38, 149 Print preview 159160 in Visual C++ 7 Print Preview command (File menu) 38, 159 Print Preview toolbar button 42 Print titles 77 Print Titles command (File menu) 38 Print toolbar button 42 PrintArea property 151 PrintAreaLocal property 151 PrintFooter property 156 PrintHeader property 156 Printing 149160 from print preview screen 160 headers and footers 156157

307

Printing (continued) in Visual C++ 7 margins 154 page breaks, setting and removing 152153 page numbers 155 page order 158 paper size 158 portrait or landscape 157 print area 150151 print preview 159160 row and column headings 159 scaling data 157 sizing data to fit pages 155 titles 151 PrintLandscape property 157 PrintPreviewDCEx method 7, 160 PrintPreviewEx method 160 PrintScale property 158 PrintTitles property 152 PrintTitlesLocal property 152 PRODUCT function 264 PROPER function 264 Properties command (Format menu) 41, 55, 56, 62, 82, 85 Properties command (Format Sheet menu) 86 Properties of Formula One in PowerBuilder 19 in Visual Basic 9 in Visual C++ 8 Properties, entering data with 64 Protecting the worksheet 8182 Protection command (Format menu) 41, 81 ProtectionDlg method 52 ProtectionHidden property 52, 81 ProtectionLocked property 52, 81 PV function 265

Q
Querying databases 164 QueryInterface 192

R
RAND function 78, 266 Ranges building to optimize memory 177 copying data across 93 deleting 98 editing, using methods 92 filling 74 naming 76 references as function arguments 74

308

Formula One ActiveX Users Guide

ROUNDUP function 273 Row Default Height command (Format menu) 40 ROW function 272, 273 Row headings formatting 119 hiding 56 preventing changes to 82 preventing resizing of 86 printing 159 selecting 119 sizing 120 text of 120121 Row Height command (Format menu) 40 Row Hide command (Format menu) 40 Row mode 62 Row property (F1FindReplaceInfo object) 95 Row Unhide command (Format menu) 40 RowHeadings property 159 RowHeight property 52, 114 RowHeightDlg method 52, 114 RowHidden property 114 RowMode property 62 Rows applying number formats 101 building to optimize memory 177 deleting 98 freezing 115 headings (see row headings) inserting 96 maximum height 180 preventing selection of 62 print titles and 151 selecting 61 selecting, with row mode 62 setting heights of 110114 automatically 111, 112, 113 default 111 dialog box for 112 Rows command (Insert menu) 39 ROWS function 78, 274 RowText property 52, 121

Ranges (continued) references in formulas 6971 selecting 57, 60 source, for charts 141 writing to file 34 RATE function 266 Read command (File menu) 37 Read method 20, 33 Read toolbar button 42 ReadEx method 20, 33 ReadFromBlob method 33 Reading BLOBs 33 Excel-compatible files 32 Formula One files 32 HTML files 32 tabbed text files 32 Read-only, making workbook 8081 Recalc command (Tools menu) 41 Recalc method 78 Recalculation automatic workbook 77 circular references and 79 minimal 78 workbook 58, 7779 Rectangle command (Insert menu) 40 Rectangles creating 123125 tool for 124 #REF! error 72 Reference operators (for cell ranges) 68 References to cells. See Cell references Relative cell references 70 in validation rules 82 Remove Page Break command (Insert menu) 153 RemoveColPageBreak method 153 RemovePageBreak method 153 RemoveRowPageBreak method 153 Renaming worksheets 55 Repaint property 177 Repaint, disabling to optimize memory 177 Replace command (Edit menu) 39 Replace dialog box 94 REPLACE function 267 Replace method x, 95 REPLACEB function 269 ReplaceDlg method 95 REPT function 269 Retrieving data from databases 164 Right Align toolbar button 43 RIGHT function 270 RightMargin property 154 ROUND function 271

S
Safe events, understanding 175 Save As command (File menu) 37 Save command (File menu) 37 Save toolbar button 42 SaveFileDlg method 33, 171 SaveFileDlgEx method 33, 171 Scale for printing data 157 for viewing worksheets 56

Index
Scientific notation, formatting numbers as 100, 103 Scripts, in fonts 47, 107 Scroll lock key 59 Scrolling mode 57 SEARCH function 274 SEARCHB function 275 Searching for and replacing data 94 SECOND function 276 SelChange event 31 Select All Objects command (Edit menu) 38, 129 Selecting cells 6061 graphical objects 128130 row and column headings 119 rows and columns 57, 61 user options for 62 using the mouse 57 with properties and methods 61 with the keyboard 5859 with the mouse 60 worksheets 5051, 57 Selection property 61 SelectionCount property 61 SelectionEx property 61 SelHdrCol property 119 SelHdrRow property 119 SelHdrTopLeft property 119 Send to Back command (Format menu) 41, 132 Serial number, for Formula One x, xi Series labels, on charts 143 Set Print Area command (File menu) 150 Set Print Titles command (File menu) 152 SetAlignment method 52 SetBorder method 52 SetBorderEx method 52 SetCellFormat method 52, 81, 117 SetColWidth method 52, 114 SetColWidthAuto method 66, 114 SetColWidthTwips method 114 SetDefaultFont method 47 SetDefaultFontEx method 47 SetFont method 52 SetFontEx method 52, 107 SetHdrSelection method 119 SetIteration method 79 SetLineStyle method 128, 135 SetPageSetup method 52 SetPattern method 52, 118, 128, 133 SetProtection method 52 SetRowHeight method 52, 114 SetRowHeightAuto method 114 Setup.exe file xi SetValidationRule method 52

309

Sheet limits 56 Sheet Properties command (Format menu) 41, 55, 56, 62, 82, 85, 86, 116 Sheet property 31, 46 Sheet Protection command (Format menu) 41, 81 SheetName property 55 SheetSelected property 51, 53, 54 ShowColHeading property 56 ShowEditBar property 46, 64, 81 ShowEditBarCellRef property 46, 64 ShowFormulas property 56, 72 ShowGridLines property 56 ShowHScrollBar property 57 ShowLockedCellsError property 82 ShowRowHeading property 56 ShowTabs property 31, 46 ShowTypeMarkers property 46, 177 ShowVScrollBar property 57 ShowZeroValues property 56 SIGN function 276 SIN function 277 SINH function 277 Sizing graphical objects 130132 SLN function 278 Sort command (Edit menu) 38 Sort method 98 SortDlg method 98 Sorting data 98 Specifications 180 SQRT function 278 SSClearRange function call 98 SSDeleteRange function call 98 SSEditClear function call 98 Stacking, on charts 143 Standalone Workbook Designer 36 Standard Toolbar command (View menu) 39 StartCol property 131 StartRow property 131 Status Bar command (View menu) 39 STDEV function 279 STDEVP function 279 String 184 Strings, in formulas 68 Style page, in Chart Wizard 143 SUBSTITUTE function 280 SUM function 280 SUMIF function 281 SUMPRODUCT function 282 SUMSQ function 282 SYD function 283

310

Formula One ActiveX Users Guide

TYPE function 289 Type markers 46

T
T function 284 Tabbed text, reading and writing files 32 Tabs, worksheet displaying 46 enlarging space for 49 hiding 31, 46 TAN function 284 TANH function 285 Technical specifications 180 Templates, for applications in PowerBuilder 11 Text displayed next to check boxes 136 displayed on buttons 137 entering 67 obtaining formatted 101 TEXT function 285 Text operators 68 Text property 52, 65 TextRC property 52, 65 TextSRC property 52 Thread safety and F1Functions 184 3D charts 143 Tidestone Technologies, Inc. Case Tracking System xii contact information xii Europe office xiii website 171 TIME function 286 Times entering 67 formatting numbers as 101, 104 printing, in headers and footers 157 TIMEVALUE function 286 Title property 70 Titles, for charts 144 TODAY function 78, 287 Toggle Drawing Toolbar toolbar button 42 Toolbars 36, 4244 docking 37 Tools menu, in Workbook Designer 41 TopLeftText property 52, 121 TopMargin property 154 Top-to-bottom printing 158 TRIM function 287 TRUE function 288 TrueType fonts 47, 106 TRUNC function 288 TTF16.h file 2 Tutorials, using PowerBuilder 1018 2D charts 143

U
Underline toolbar button 43 Unfreeze Panes command (Format menu) 41 Uniform Data Transfer 93 Updating database data 167 Upgrading 20 UPPER function 289 USDOLLAR function 290 Users limiting access 46, 8086 to cells 8182 to certain keys 85 to changing row and column headings 82 to charts 146 to entering certain values 82 to entering formulas 85 to graphical objects 129 to mouse actions 86 to workbook areas 30 to workbooks 8081 setting selection options for 62

V
Validating data 82 Validation rules 82 ValidationFailed event 84 ValidationRule property 84 ValidationRuleDlg method 52 ValidationRuleLocal property 84 ValidationRuleLocalRC property 84 ValidationRuleRC property 84 ValidationText property 84 VAlign property 52 #VALUE! error 72 VALUE function 291 VAR function 291 Variant 184 VARP function 292 VDB function 292 Versions of Formula One 21, 33 View menu, in Workbook Designer 39 View scale, for worksheets 56 Views attaching 27, 30 information stored with 26 saving 32 working with 26

Index
ViewScale property 56 Visual Basic 89 adding the Formula One component 89 properties and methods, for Formula One 9 Visual basic using add-ins in 183 Visual C++ 18 adding the Formula One component 36 Formula One objects in 6 handling Formula One events 7 printing and previewing in 7 properties and methods, for Formula One 6, 8 serializing the Formula One control in 7 VLOOKUP function 293 Workbooks (continued) See also F1Book API object Worksheet command (Insert menu) 39, 53 Worksheet functions. See Functions Worksheets active 50 building to optimize memory 177 cells in borders for 116118 clearing 98 data alignment in 107108 deleting 98 inserting 96 locking 8182 data entry of 6365 constant values in 6667 formulas in 6772 limiting 8086 multi-line 65 data types in 66 deleting 54 display options 5556 external references in 71 formatting 99108 index list of 31, 50, 53, 71 inserting 49, 52 limiting rows and columns displayed 5556 maximum size 180 naming 55 navigating in 5659 performing tasks on multiple 50 preventing selection of 62 printing 149 referencing in cell references 70 selecting 5051 selection in cells 6061 rows and columns 61 sorting data in 98 tabs on 46 working with a group 51 Wrapper classes, in Visual C++ 6 Wrapping text 108 Write command (File menu) 37 Write method 33 WriteEx method 33 WriteRange method 34 WriteRangeEx method 7, 34 WriteToBlob method 33 WriteToBlobEx method 33 Writing a range of cell data 34 BLOBs 33

311

W
Web pages containing Formula One 173 WEEKDAY function 294 Weight, line 134 White space 177 Width command (Format menu) 112 Windows metafiles, importing 125 Windows Registration Database xi WordWrap property 52, 108 Workbook Designer 25, 3544 Edit menu commands 38 File menu commands 37 Format menu commands 40 Insert menu commands 39 keyboard commands 58 launching 36 menus 3741 mouse actions 57 standalone 36 toolbars 42 Tools menu commands 41 View menu commands 39 Workbooks attaching views to 26, 30 calculating 7779 automatically 77 circular references and 79 deleting worksheets from 54 denying user access to 8081 description of 24 display options 30, 4548 index sheet list in 50, 53 inserting worksheets in 49, 52 reading 32 retrieving, from database tables 33 selecting worksheets in 5051 writing 32

Writing (continued) Excel-compatible files 32 Formula One files 32 HTML files 32, 171 tabbed text files 32

X
X axis labels, on charts 144

Y
Y axis labels, on charts 144 YEAR function 295

Z
Z axis labels, on charts 144 Zero values, displaying or hiding 56 Zooming in and out in printing worksheets 157 in viewing worksheets 56