QuickFigure Tools Overview
By Don A. Vollum
PelicanWare, Inc.
donv@teleport.com

550 SW Park Avenue
Suite 270
Portland, OR  97205

	When we  first developed QuickFigure, we quickly found that we couldn't anticipate all of the uses people would find for a Newton spreadsheet. Early applications ranged from creating invoices and doing statistical analysis to calculating a position based on star sightings. To accommodate these varied activities, we designed QuickFigure Pro to be easily extensible, through the addition of the QuickFigure Tools API.
	At the same time, we felt that it was important to provide a means for other Newton applications to exchange data with QuickFigure. For example, many people would find it useful to be able to transfer data between QuickFigure Pro and a database application.

What are quickfigure tools?

	There are two types of application which use the QuickFigure Tools API, "QuickFigure Tools" and "QuickFigure-Compatible Applications." QuickFigure Tools are small applets which only exist to  manipulate or use data from a QuickFigure worksheet. For example, QuickFigure Pro 2.1 includes a QuickFigure Tool called "QSort." This tool sorts whatever data is selected in QuickFigure, and reinserts the sorted data into the worksheet. Other examples of QuickFigure Tools include statistical tools, equation solvers, communications tools (which can read information in from the serial port, or a remote server), and forms-based data entry tools.
	Since QuickFigure Tools can be activated from QuickFigure's Tools menu, they are often auto-parts. Auto-parts have the advantage of using less of the Newton's scarce heap memory, and do not add clutter the Extras Drawer. However, they can confuse users when trying to remove the application from the Newton.
	QuickFigure-Compatible Applications are independent applications which create or manipulate QuickFigure worksheets. These applications can export data to QuickFigure for analysis, or can import data from a QuickFigure worksheet.

Requirements

	QuickFigure Pro 2.1 or QuickFigure Lite 2.1 are currently the only versions of QuickFigure which support the complete QuickFigure Tools API. QuickFigure Pro 2.0 has very limited support for the API, and isn't compatible with most QuickFigure Tools.
	QuickFigure Tools and QuickFigure Compatible Applications can be created with either the Newton Toolkit or the Newt Development Environment. 

the quickfigure tools api

QuickFigure Tools Interface

	The QuickFigure Tools API has two parts: the QuickFigure Tools interface, which allows an application to exchange data with QuickFigure and appear in QuickFigure's Tools menu; and QuickFigure Tools scripting methods, a group of methods which allow an application to manipulate QuickFigure worksheets and control various QuickFigure functions.
	To support the QuickFigure Tools interface, an application must do two things: register itself with QuickFigure by adding some information to a slot in the Newton's root, and support the ddxScript() method. The ddxScript method is used by QuickFigure to activate the tool when the user selects it from QuickFigure's Tools menu. In addition, I recommend that developers define the ddxFrom slot in their applications, where QuickFigure places its symbol when the Tool is activated.
 	When QuickFigure Pro is installed on a Newton, it adds a slot to the Newton's root called "qfTools:qfig:donv." To register a tool with QuickFigure, the application needs to add a frame to the qfTools slot as follows:

{name: "My Tool",path: 'myTool:donv}

	When the user taps on the Tools button in QuickFigure, they will see a list of tools, including "My Tool." When "My Tool" is selected from the Tools menu in QuickFigure, QuickFigure will send a ddxScript() message to getRoot().|myTool:donv|. 
	 The ddxScript message includes information about the cells currently selected in QuickFigure: the number of rows and columns selected, and an array containing the contents of those cells. QuickFigure also adds a reference to itself in the Tool's ddxFrom slot.
	If the Tool is modifying the cells which are currently selected in QuickFigure, it can send QuickFigure the ddxScript() message when closing. QuickFigure's ddxScript() method inserts data into the currently selected cells, and allows the user to Undo the changes using the Newton's standard Undo button.

QuickFigure Tools Scripting Methods

	QuickFigure Tools scripting methods are a documented subset of QuickFigure's internal methods. They can be used to examine or modify the contents of individual cells, create new worksheets, open worksheets, and delete worksheets.
	For example, you could find out the value of cell A4 in the current QuickFigure worksheet by sending QuickFigure the getValue() message from the inspector:

getRoot().|qfig:donv|:getValue('a4)
#4415281  26.6969

	Similarly, you could find out if there is a formula in that cell, and if so what it is, by sending QuickFigure the getFormula() message from the inspector:

getRoot().|qfig:donv|:getFormula('a4)
#4419879  "=A2+POW(A3,0.75)"

Developing a forms-based data entry tool

	QuickFigure Tools are a very fast way to create forms-based data entry applications. They allow a developer to take advantage of many features implemented within QuickFigure, including data storage, complete routing support, and export to the desktop. In addition, data collected with the form can be easily analyzed in the spreadsheet format.
	For example, I will design a simple Expense Slip form to enter my travel expenses. This tool will be a simple form to enter data. After the data has been entered, the Expense Slip will generate a new QuickFigure worksheet with the data and a formula to display a total.

Designing the User Interface

	I created a user interface in NTK. In this case, I am using a protoFloatngo, containing several input lines and static text labels, and two buttons. Tapping on the "Date" label brings up a calendar view to enter a date with, and  the "Enter" button inserts the data into the QuickFigure worksheet 	

The Expense Slip User Interface

The Calendar view.

	It is important to make sure that the viewFlags slot of the floater has the vClickable flag set. Otherwise, taps on the floater will fall through to the underlying application, which is a problem if the floater is on top of QuickFigure (almost all of QuickFigure's base view processes taps). 	For most QuickFigure Tools, the main view should be draggable. If you choose to do this, remember that you need to check the coordinates of the tap against the bounds of the view. For example, in the Expense Slip application, I have the following code in the base view's viewClickScript:

 local tapX := getpoint(firstX,unit);
 local tapY := getPoint(firstY,unit);
 local myBounds := getRoot().(kAppSym):globalBox();

 if tapX < myBounds.left+3 
	or tapX > myBounds.right-3
	or tapY < myBounds.top +3
	or tapY > myBounds.bottom-3 then
		getRoot().(kAppSym):drag(unit,nil);

	To update the total label, I added an idler, which is called whenever one of the input lines is sent the viewChangedScript message. It simply adds the contents of the various fields and puts the resulting value into the total label.
	Since the Expense Slip  is intended to create a QuickFigure worksheet, the next step is considering how the resulting worksheet should appear. I put together a worksheet which is in the format the application will generate, and noted the cell names.

QuickFigure Worksheet Template

Integrating with QuickFigure

	Now that the user interface is done, it is time to add some QuickFigure integration. The first step is to define a ddxScript method in the Tool's base view. In it's simplest form, all the ddxScript method needs to do is open the Tool:

func(rows,columns,data,name)
begin
 self:open();
end

	The parameters refer to the cells which are selected in QuickFigure. If the Expense Slip were an auto-part, you could put initialization code in this script. Because it is a form part, however, any initialization code should be added in the viewSetupFormScript or viewSetupDoneScript.
	After defining the ddxScript method, the next step is to add an evaluate slot to the base view, named "ddxFrom." QuickFigure will fill in this slot with it's symbol when the tool is activated.

Exporting the Data to QuickFigure

	Most of the integration with QuickFigure takes place in the Enter button's buttonClickScript. This script opens QuickFigure, creates a new worksheet, adds the necessary labels, and then fills in the values of the cells using the data from the various input lines. Finally, it adds a formula to cell D12 which calculates a total.
	The script first checks for a ddxFrom value. If the app was opened using the Extras Drawer, and not QuickFigure's Tools menu, then QuickFigure's symbol needs to be added. Then, it opens QuickFigure and creates a new worksheet:

 /* validate the ddxFrom slot (if this app is opened from the Extras Drawer,
   the ddxFrom slot might not be filled in): */

 if not ddxFrom then ddxFrom := '|qfig:donv|;

 //open QuickFigure, if it isn't already open.
 if not visible(getRoot().(ddxFrom)) 
	then getRoot().(ddxFrom):open();
 
 //create a new worksheet:
 getRoot().(ddxFrom):newSheetScript(nil,nil);

	Next is the code which adds the cells to the worksheet. QuickFigure provides two methods for this purpose: addCell() and parseEntry(). Both of these methods accept anything which can be entered into a QuickFigure cell normally – data, formulas, etc. The difference between the two is that addCell() causes QuickFigure to redraw the display, while parseEntry() does not. This means that parseEntry() is significantly faster; however, you must call addCell() after adding the last item, so the screen is updated.
	
 //fill in the labels:
 getRoot().(ddxFrom):parseEntry("Expenses" && date.text,'a1);
 getRoot().(ddxFrom):parseEntry("Breakfast",'a4);
 getRoot().(ddxFrom):parseEntry("Lunch",'a5);
 getRoot().(ddxFrom):parseEntry("Dinner",'a6);
 getRoot().(ddxFrom):parseEntry("Hotel",'a8);
 getRoot().(ddxFrom):parseEntry("Misc.",'a10);
 getRoot().(ddxFrom):parseEntry("Total:",'b12);

 /* fill in the numbers (the $ makes QuickFigure format 
 the number as currency): */

 getRoot().(ddxFrom):parseEntry("$" & breakfast.text,'c4);
 getRoot().(ddxFrom):parseEntry("$" & lunch.text,'c5);
 getRoot().(ddxFrom):parseEntry("$" & dinner.text,'c6);
 getRoot().(ddxFrom):parseEntry("$" & hotel.text,'c8);
 getRoot().(ddxFrom):parseEntry("$" & misc.text,'c10);
 getRoot().(ddxFrom):addCell("=c4+c5+c6+c8+c10",'d12);

	Since the parseEntry() and addCell() methods can accept anything that could normally be entered into a QuickFigure worksheet, you can specify that numbers be formatted in currency format by preceding the number with a dollar sign. Unfortunately, this trick only works with literals, and cannot be used with formulas.
	Finally, the tool closes itself:

//close self:
 self:parent():close();

The quickfigure developer's kit

	The QuickFigure Developer's Kit provides complete documentation on the QuickFigure Tools API, as well as sample code, and information on updates to the QuickFigure Tools API. The samples include a less-robust version of the sorting tool which comes with QuickFigure Pro 2.1, and a tool which receives data through the Newton's serial port from a Trimble GPS receiver. 
	The Developer's Kit is free to registered QuickFigure Pro users.

conclusion

	The QuickFigure Tools API allows you to easily extend QuickFigure Pro, or integrate your application with it. It also lets you take advantage of QuickFigure's many features in your applications with very little effort.

Bibliography

QuickFigure Developer's Kit, PelicanWare, Inc.

QuickFigure Pro 2.1 User's Guide, PelicanWare, Inc.

Newton Programmer's Guide, Apple Computer, Inc.