QUICKFIGURE

Developer’s Guide

Copyright 1994-1998 PelicanWare, Inc. All Rights Reserved.

Version 1.1
11/12/96, revised 4/3/98

QuickFigure Tools Documentation

Copyright 1994 - 1998 PelicanWare, Inc. All Rights Reserved.

Introduction

Overview

QuickFigure Works is a fast, extensible spreadsheet for devices based on the Apple Newton operating system. This document describes the creation of QuickFigure extensions (known as “QuickFigure Tools”), and is a reference to the API provided by QuickFigure for Tools.

QuickFigure Tools are Newton applications which are compatible with QuickFigure, and which may be either stand-alone applications or auto-parts accessed through the Tools button in QuickFigure. When the Tools button is pressed, QuickFigure searches for registered applications, and presents the user with a pick-list of tools. When the user selects a tool, the tool is passed the contents of any selected cells and a reference to QuickFigure. When user exits the tool, the contents of the cells are passed back to QuickFigure, and are re-entered in the specific cells.

Tools may be either complete, stand-alone applications which are interfacing with QuickFigure, or dedicated extensions which are only useful in combination with QuickFigure.

QuickFigure Tools may be created by Newton Toolkit, or other development tools capable of creating Newton applications. Other development tools available include the Newt Development Environment, and NS BASIC.

Applicability

This document describes the QuickFigure Tools interface for QuickFigure Works Version 1.0 and subsequent. This interface is a subset of the API available for QuickFigure Pro 3.x and subsequent, and so should be usable with QuickFigure Pro 3.x as well.

This document is oriented around Tools created with the Newton Toolkit, and assumes that you have a basic level of familiarity with Newton Programming, the Newton Toolkit, and NewtonScript. It also assumes a basic familiarity with spreadsheets, and with QuickFigure specifically.

Creating QuickFigure Tools

Creating QuickFigure Tool AutoParts

If you are creating a dedicated QuickFigure Tool (i.e. a Tool meant to be accessed only through QuickFigure, rather than a stand-alone application), then we recommend that you make the tool an autopart. This conserves space in the extras drawer, and reduces the use of system resources.

When using an autopart, be very careful about avoiding card-removal errors (“Newton Needs the Card...”). Refer to the sample projects for guidance, and do lots of testing!

Tool Registration

QuickFigure Works supports both the NewtWorks Tool registration API and the QuickFigure Tool registration API. However, tools which are registered using the NewtWorks Tools registration functions will not be visible to QuickFigure Pro. 

If the tool is designed only to work with QuickFigure Works (and will not be used with QuickFigure Pro), then you should use the NewtWorks Tool API, which is summarized below. Otherwise, you should use the standard QuickFigure Tools registration API, which is described in the next section.

Registering a NewtWorks Tool

To register a tool with NewtWorks, you must send NewtWorks the RegNewtWorksTools and UnRegNewtWorksTools methods. For example:

getRoot().newtworks:RegNewtWorksTool(toolSym,toolFrame);
getRoot().newtworks:unregNewtWorksTool(toolSym);

toolSym is a unique symbol which should include your developer signature.
ToolFrame is a frame with the following slots:

dataTypeSymbol: 	A symbol which identifies which Works document type to register with. This will be |qfnewt:donv| for QuickFigure Works tools.

item:	The text to appear in the QuickFigure Works Tools menu.

cmdFunc:	The function that will be invoked when the tool is selected from the Tools popup. Two arguments will be passed to cmdFunc by Works -- a reference to the QFWorks worksheet, and a reference to NewtWorks. This is where you can initialize and open your tool. 

For an example of registering a tool using the NewtWorks registration method, see the Works-ScrollerTool sample project included with this API document.

Compatibility Note: Registering a tool as a NewtWorks tool may not work properly in QuickFigure Works 1.0. It should work properly in version 1.0.1 and subsequent.

QuickFigure Tools Registration

QuickFigure Tools which are currently installed on the system may register by adding a frame to the “qfTools:qfig:donv” array stored in the root view. The frame must include the following slots:

{name:	‘toolNameString,
 path:	‘toolPath}

toolNameString refers to the name the user will see when he or she taps on the Tool button, and is presented with the pick-list of installed tools.

toolPath is a symbol containing the path to the tool from the root. It must be unique, and should contain the Tool developer’s signature, in accordance with standard Newton application symbol guidelines. To open the Tool, QuickFigure will send the following message:

	getRoot().(ToolPath):ddxScript(xxx...);

The Tool should check to see if the qfTools:qfig:donv array has been created, and then add it’s information to the array. If the array has not been completed, then the Tool should create it (make sure that both the “qfTools:qfig:donv” symbol and the array are created in internal memory). For example:

toolInfo := {name: “Tool Demo”,path: ‘|toolDemo:donv|};

if not getRoot().|qfTools:qfig:donv| then getRoot().(ensureInternal(‘|qfTools:qfig:donv|)) := 	ensureInternal([]); 	

addArraySlot(getRoot().|qfTools:qfig:donv|,toolInfo);

Tool Removal

If the tool was registered using the QuickFigure Tools registration process, then the removeScript of each QuickFigure Tool should send remove its entry from the qfTools:qfig:donv frame. This should be done as follows:

infoPos := arrayPos(getRoot().|qfTools:qfig:donv|,toolInfo);
arrayRemoveCount(getRoot().|qfTools:qfig:donv|,infoPos,1);

Required Slots

Tools must have the following slots:

ddxScript(numColumns,numRows,cellArray,toolName);
ddxScript is a method. This script is how QuickFigure opens the Tool, and it must accept the following parameters:

   numRows		An integer representing the number of rows of data being sent.

   numColumns	An integer representing the number of columns being sent.

	   cellArray		An array containing the contents of the selected cells. The length of 	the array is equal to the number of rows times the number of columns. The array 	elements may be strings, integers, real numbers, or nils.

   toolName		A string containing the name of the Tool, as displayed when the user taps the “Tools” button in QuickFigure. This parameter is passed for Tools operating in a run-time environment, such as NS-BASIC.

Note: The toolName parameter is not reliable in QuickFigure Pro 2.1. It is fully supported in subsequent versions of QuickFigure Pro and QuickFigure Works.

ddxFrom

ddxFrom is a reference to the QuickFigure application which opened the tool. This allows the tool to send messages back to QuickFigure, and to control QuickFigure using the QuickFigure API.

Opening the Tool

When the Tools button in QuickFigure is depressed, the names of the installed tools are displayed in a pick list. Depending on whether the tool has been registered via the QuickFigure Tools mechanism of the NewtWorks Tool mechanism, the following occurs:

Tools registered via the QuickFigure Tools mechanism:
1.  Sets the Tool’s ddxFrom slot: 
getRoot().(toolPathSymbol).ddxFrom := self;

2. Sends the Tool the :ddxScript message:         getRoot().(toolPathSymbol):ddxScript(numColumns,numRows,cellArray,toolName);

The ddxScript should do any necessary pre-processing, and open the Tool itself. If the Tool does not have a user interface, then the Tool should do whatever processing it needs to, and return the data.

Returning Data to QuickFigure

When processing is complete, the Tool should return the modified data to QuickFigure and close itself. It should do this by sending QuickFigure the :ddxScript() message, and then closing itself. QuickFigure’s ddxScript method accepts three arguments: numRows, numColumns, and dataArray.

QuickFigure’s ddxScript method automatically provides undo support. If the user taps “Undo” after a QuickFigure Tool has returned information to QuickFigure, then the cells which were modified will be returned to their original state.

dataArray must be an array of strings, even if the value being entered is a number. For example:

getRoot().|qfig:donv|:ddxScript(3,2,["1","2","3","4","5","6"])
#1A       TRUE

After returning the data through the ddxScript call, the Tool should then call it’s own :close() method. This call should be made from within a deferred action.

Note: If the Tool is not processing data passed to it through by the ddxScript, do not return to QuickFigure by calling QuickFigure’s ddxScript. Instead, simply do whatever processing is necessary and close the Tool. 

If the Tool does pass values back to QuickFigure, these values will overwrite the existing data in QuickFigure, even if the data has not changed. If the QuickFigure range contained formulas, these will be overwritten with values.

Scripting QuickFigure From Within A Tool

Introduction

Overview

Any application or tool may add or modify data in a QuickFigure worksheet, create new worksheets, and otherwise control QuickFigure through several QuickFigure messages (the QuickFigure Tools API). These messages must be sent to the QuickFigure main view and are documented in the following sections. In most cases, these messages must be sent when QuickFigure is open.

In the application or tool’s base view, the ddxFrom slot will contain a reference to QuickFigure, so these messages should be sent to ddxFrom.

TIP:  For the purpose of working through many of these examples, it is useful to set up a ddxFrom reference in the Inspector. Provided that QFWorks is open, the following code will accomplish this:

ddxFrom := getRoot().newtworks.viewDefView

To set up a reference to QuickFigure Pro, use the following code:

ddxFrom := getRoot().|qfig:donv|

Finding Information about the Version of QuickFigure

The version information for QuickFigure can be retrieved by sending the “getVersion” message The syntax of this message is:

ddxFrom:getVersion();

For example:

ddxFrom:getVersion()
#60067A2D "QuickFigure Works Version 1.1b5c2"

Retrieving Data from a QuickFigure Worksheet

Retrieving the Contents of A Cell or Range of Cells

To get the contents of a particular cell, you must send QuickFigure the “:getValue()” message. The syntax for this message is:

ddxFrom:getValue(CELLSYMBOL);

CELLSYMBOL is a symbol representing the cell name-- A1, for example.  cellSymbol is not case-sensitive.

This method will return the value of the cell. This value may be a integer or a real number, or a string (if the cell contains a label). For example:

ddxFrom:getValue('b3)
#440EAA9  5.00000

If the cell has a formula, you can get this by sending the “:getFormula()” message. The syntax for this message is:

ddxFrom:getFormula(CELLSYMBOL);

If the cell has a formula, this message will return the formula. Otherwise, it will return the value of the cell. For example:

ddxFrom:getFormula('c4)
#4417E69  "=C3+5"

You can determine if a cell contains a formula by checking the first character returned by :getFormula(). If that character is an “=” then the cell contains a formula. The following code tests for this condition:

MyString := getFormula(‘a1);
if strEqual( (subStr(myString,0,1)), "=") then
print ("is a formula")
else 
print("not a formula");

Getting The Formatting Data for a Cell

To get the formatting data for a given cell (numeric, number of decimal places, and text), you should use the :getCellFormat() message. The syntax is:

ddxFrom:getCellFormat(CELLSYMBOL);

This method returns a frame, with the following slots:

decimalPlaces:		An integer representing the number of decimal places for numbers in that cell. Nil if no set number of decimal places are specified.

NumericFormat:	An integer representing the numeric format setting for the cell. In QuickFigure, the settings are as follows:

	1	Percentage
	2	Group Separator (“0,000”)
	3	Currency
	4	Scientific

If no numeric format is specified, this slot will have a value of nil.

textFormat:		A format frame, containing a font specification, a penPattern slot, and a justification slot. If no textFormat is specified for this cell, this slot will contain the frame with the default text format for the worksheet.

If the cell does not exist, then this method returns nil.

For example:

ddxFrom:getCellFormat('b2)
#441E5B9  {decimalPlaces: 0, 
           numericFormat: 3, 
           textFormat: {font: {family: espy, 
                               face: 0, 
                               size: 12}, 
                        penPattern: vfBlack, 
                        justification: left}}

Note: Numeric formatting uses the values specified in the Newton’s getLocale() function for currency symbols and the group separator.

Determining Which Cells are Selected in QuickFigure

To find the currently selected cell or cells, you should send QuickFigure the :getCurrCell() message. The syntax for this message is:

ddxFrom:getCurrCell();

This message will return an array containing strings representing the selected cells in QuickFigure. For example:

ddxFrom:getCurrCell()
#441A7E1  ["C3", "C4", "C5", "D3", "D4", "D5"]

Selecting a Range

A range of cells may be selected by sending QuickFigure the selectRange message. The syntax for this message is:

ddxFrom:SelectRange(range);

This message will select the range and update the display. For example:

ddxFrom:selectRange("A1:B3")
#2        NIL

Getting Cell References for a Range

To  convert a range from the “firstCell:lastCell” format, you can use QuickFigure’s :evaluateRange() method. The syntax is:

ddxFrom:evaluateRange(rangeString)

rangeString is a string in the format “firstCell:lastCell.” For example:

ddxFrom:evaluateRange("A1:B3")
#441C2C1  ["A1", "A2", "A3", "B1", "B2", "B3"]

Note:  :evaluateRange() has two potentially dangerous characteristics. First, it doesn’t deal well with bad data, so be sure to wrap it in a “try...onException” handler. Second, it returns the cell names as strings, so they must be converted into symbols to be useful.

Creating a New QuickFigure Works Document

QuickFigure Works 1.1 includes a new dataDef method, createSheetFromText. This method allows you to create a new QuickFigure Works document and fill it with data while QuickFigure Works is closed.

The syntax for this message is:

dataDef:createSheetFromText(sheetName, textData);

sheetName is a string to be used as the name of the document. TextData is a string containing the data to be entered in the worksheet, in tab-separated format. The return value of the method is the entry itself.

For example:

myEntry := getDataDefs('|qfnewt:donv|):createSheetFromText
              ("test sheet", "1	2	3	4")

#C418385  {class: |QFNewt:donv|, 
           viewStationery: |QFNewt:donv|, 
           title: "test sheet", 
           timeStamp: 48691866, 
           prefs: {}, 
           cells: NIL, 
           cellEmptyList: [], 
           newSheet: NIL, 
           lastAddress: 1, 
           lastCellIndex: NIL, 
           cellAddresses: <binary, length 8004>, 
           version: 2, 
           textWorksheet: "1	2	3	4"}

Note: createSheetFromText does not store the newly created entry in a soup. However, the entry returned by this function is complete, and may be added directly to the Newton Works soup. Here is an example of how myEntry as defined above would actually become a QuickFigure Works spreadsheet:

mySoup := getUnionSoup(“newtWorks”);
mySoup:addToDefaultStore(myEntry);

Manipulating QuickFigure Pro Worksheets 

The following section refers to functions that are possible with QuickFigure Pro but not QuickFigure Works.

QuickFigure records when a worksheet has been changed, and automatically saves any changes during idle time (this is accomplished through a viewIdleScript which is activated every 5 seconds).

Worksheets are not created until QuickFigure attempts to save. Then, if there is no current worksheet, QuickFigure will create one.

Creating a New QuickFigure Pro Worksheet

To create a new QuickFigure Pro worksheet, you need to send QuickFigure the “:newSheetScript()” message. The syntax of this message is:

ddxFrom:newSheetScript(nil,nil);

Both of the arguments to the newSheetScript message are ignored. For example:  

ddxFrom:newSheetScript(nil,nil)
#1A       TRUE

This function will save any changes to the current worksheet, close it, and reset QuickFigure. A new QuickFigure soup entry is not created until the first change is made to the new worksheet. 

Deleting A QuickFigure Pro Worksheet

QuickFigure worksheets can be deleted through the deleteActionScript() message. To use this message, QuickFigure must be open, and the worksheet must be open. The deleteActionScript will prompt the user with a warning that deleting a worksheet cannot be undone. If the user accepts the warning, the standard Newton delete animation will be shown, the worksheet will be deleted, and QuickFigure will be reset (essentially the newSheetScript() method will be called).

The syntax of the deleteActionScript message is:

ddxFrom:deleteActionScript(nil,nil)

For example:

ddxFrom:deleteActionScript(nil,nil)
#1A       TRUE

The parameters to deleteActionScript are ignored.

Modifying the Contents of a QuickFigure Worksheet

Adding or Changing a Cell

You may enter a new value or formula into a QuickFigure worksheet by using the “:addCell()” method. This method enters the data into a cell and refreshes the display. :addCell() may also be used to change the contents of an existing cell.

The syntax for this message is:

ddxFrom:addCell(TEXT,CELLSYMBOL);

TEXT is a string containing the value or formula. Note: Even if you want to enter a number, it must be formatted as a string for the :addCell() function.

CELLSYMBOL is a symbol representing the cell you wish to enter the data into. For example:

ddxFrom:addCell("45",'b2)
#4415E79  45.0000

ddxFrom:addCell("=b2+5",'b3)
#4417BD9  50.0000

If you wish to delete a cell, you should send QuickFigure the following message:

ddxFrom:addCell(“”,CELLSYMBOL);

For example:

ddxFrom:addCell("",'b3)
#2        NIL

Alternatively, you can use the AddCellWithUndo message to add a single cell, and provide undo support if the user may wish to undo the action. Please note that the undo support only applies to the last cell added with this method, so it is most useful for adding or modifying a single cell.

The parameters are identical to the AddCell method, although in reverse order, and the syntax is:

ddxFrom:addCellWithUndo(CELLSYMBOL, TEXT);

You can also add data to a QuickFigure worksheet by using the :parseEntry() message. This function acts exactly like :addCell(), except it does not update the display (and so should be faster for entering many cells at the same time). To update the display, make sure that the final cell is added through :addCell().

The syntax of the :parseEntry message is:

ddxFrom:parseEntry(TEXT,CELLSYMBOL);

For example:

ddxFrom:parseEntry("123",'a3)
#4414A79  123.000
ddxFrom:addCell("=a3+1",'a4)
#44166E1  124.000

Note that the display does not update until the :addCell() call is made.

Both the :addCell() and :parseEntry() calls mark the worksheet as changed. QuickFigure will then save the changes automatically during idle time.

Setting A Cell’s Format

The formatting information for a cell may be specified by using the setCellFormat message. The syntax for this message is:

ddxFrom:setCellFormat(cellSymbol,formatFrame)

cellSymbol is the symbol for the cell you wish to set. FormatFrame is a frame with any or all of the following slots:

decimalPlaces:		An integer representing the number of decimal places for numbers in that cell. Nil if no set number of decimal places are specified.

NumericFormat:	An integer representing the numeric format setting for the cell. In QuickFigure 2.1, the settings are as follows:

	1	Percentage
	2	Group Separator (“0,000”)
	3	Currency
	4	Scientific

If no numeric format is specified, this slot will have a value of nil.

textFormat:		A format frame, containing a font specification, a penPattern slot, and a justification slot. If no textFormat is specified for this cell, this slot will contain the frame with the default text format for the worksheet.

For example:

ddxFrom:setCellFormat('a2,{decimalPlaces: 3})
#1A       TRUE

Scrolling the Worksheet

QuickFigure can be commanded to scroll the worksheet by using the scrollScript message. 

The syntax for the scrollScript message is:

ddxFrom:scrollScript(columns,rows);

Columns represents the number of cells to scroll horizontally, while rows represents the number of cells to scroll vertically. 

For example:

ddxFrom:scrollScript(2,0)
#1A       TRUE

Storing Persistent Data With a Worksheet

Data from a tool can be stored with the current worksheet by using the setWorksheetInfo and getWorksheetInfo messages.

The syntax for the setWorksheetInfo message is:

ddxFrom:setWorksheetInfo(toolSymbol,info);

toolSymbol is a unique symbol representing the tool. It does not have to be the symbol registered by the tool, but it should include your developer signature.

Info is any information you wish to store. Remember that this information is stored as a slot in the QuickFigure soup entry, so it should not contain large amounts of data.

For example:

ddxFrom:setWorksheetInfo('|tooldemo:donv|, {item: "this is a test"})
#C421DD9  {item: "this is a test"}

The syntax for the getWorksheetInfo message is:

ddxFrom:getWorksheetInfo(toolSymbol);

toolSymbol is the symbol used to store the information.

For example:

ddxFrom:getWorksheetInfo('|tooldemo:donv|)
#C42B19D  {item: "this is a test"}

Summary of QuickFigure Tools Methods

:ddxScript(rows,cols,data,name)

Tools will be called using this method, and should also use this method to return data to QuickFigure.

ddxFrom

Tools must have this slot. It will be set by QuickFigure to be a reference to the calling application (QuickFigure).

Summary of QuickFigure Scripting Methods

:addCell(text,cellSymbol)

Sets the content of the cell “cellSymbol” to “text.” and refreshes the display.

:addCellWithUndo(cellSymbol,text)

Same as above, but with Undo support.

:evaluateRange(rangeString)

Returns an array of strings containing the cell names of the cells described by rangeString. RangeString must be in the format “firstCell:lastCell.”

:getCellFormat(cellSymbol)

If the specified cell exists, a frame containing formatting information for the cell is returned.

:getCurrCell()

Returns an array containing the symbols of each selected cell in a QuickFigure range (if only one cell is selected, that cell’s symbol is the only array element).

:getFormula(cellSymbol)

If the specified cell has a formula, the formula is returned; otherwise, the cell’s value is returned.

:getValue(cellSymbol)

Returns the value of the specified cell.

:getVersion()

Returns a string containing version information for QuickFigure.

:getWorksheetInfo( toolSymbol )

Retrieves the information stored for toolSymbol.

:parseEntry(text,cellSymbol)

Works identically to :addCell() except that the display is not refreshed.

:scrollScript(columns, rows)
		Scrolls the worksheet by a given number of columns and rows.

:selectRange(rangeString)

Selects the range specified by rangeString. RangeString must be in the format “firstCell:lastCell.”

:setCellFormat(cellSymbol, formatFrame)

Sets the formatting parameters for a specific cell.

:setWorksheetInfo(toolSymbol, info)

Stores information contained in info with the worksheet.

Note: All of the above messages must be sent to the ddxFrom reference.

Contacting PelicanWare

Support for QuickFigure developers is provided by PelicanWare Inc, on a time-available basis. PelicanWare may be contacted at any of the following addresses:

email: devsupport@pelicanware.com
WWW: www.pelicanware.com
Telephone: 503-221-1148
Fax: 503-224-0582

US Mail:

PelicanWare Inc.
506 SW 6th Ave.
Suite 1100
Portland, OR 97204