A Guide to the Newton ToolKit (Alpha Draft 1.1)

7/27/2019 A Guide to the Newton ToolKit (Alpha Draft 1.1)

1/64

A Guide to the Newton ToolKitAn Introduction to the Newton ToolkitDevelopment Environment

Alpha Draft 1.1PIE Technical Publications

July 17, 1993

Apple Computer, Inc. 1993


2/64

iii

Draft. Preliminary, Confidential. 1993 Apple Computer, Inc. 9/15/93

Contents

Preface A Guide to the Newton Toolkit viii

How to Use This Book viii

Conventions viii

Chapter 1 Installation & Setup 1-1

System Requirements 1-1

Installing NTK Software 1-1Communicating With a Newton PDA From NTK 1-2

Connecting a Newton PDA to a Macintosh 1-2

Installing the NTK Toolkit App 1-3

Connecting an Inspector 1-3

Chapter 2 A Quick Tour of NTK 2-1

Starting Up NTK 2-1

Setting Up a New Project 2-2

Starting a Base View and Adding It to the Project 2-3

Laying Out a View 2-5Customizing a View 2-6

Editing a Slot 2-7

Adding a Slot 2-8

Adding a Secondary View 2-9

Laying Out a Secondary View 2-10

Linking a Secondary View 2-12

Adding a Button That Displays the View 2-13

Storing and Retrieving Data (Using Soups) 2-14

Defining Your Own Proto Template 2-14

Laying Out a Proto and Adding It to the Palette 2-15

Using Your Proto Template 2-16

Building and Downloading a Package 2-17Using the Inspector 2-18

Chapter 3 The Newton ToolKit in Context 3-1

Development Cycle Overview 3-1


3/64


4/64

v


Find Inherited 4-6

Show Clipboard 4-6

Toolkit Preferences 4-7

Layout Settings 4-7

Browser Settings 4-8Text Views 4-8

Packages 4-8

Connection 4-9

Project Menu 4-9

New Project 4-9

Open Project 4-9

Add Window 4-9

Add File 4-9

Remove File(s) 4-9

Update Files 4-9

Build Package 4-10

Download Package 4-10Package Attributes 4-10

Install Toolkit App 4-10

Mark As Main Layout 4-10

Project Data 4-11

Settings 4-11

Application 4-11

Optimize 4-12

Copy Protected 4-12

Layout Menu 4-13

Layout Size 4-13

Autogrid On 4-13

Set Grid 4-13Move to Front, Back, Forward or Backward 4-13

Alignment 4-14

Align 4-14

Preview 4-14

Special Menu 4-15

Template Info 4-15

Allowing Access From 4-15

New Slot 4-15

Delete Slot 4-17

Rename Slot 4-17

Templates By Type, By Hierarchy 4-17

Slots By Name, By Type 4-17

Show Slot Values 4-17

Apply 4-17

Revert 4-17

Window Menu 4-17

Open Inspector 4-18

Connect Inspector 4-18


5/64

vi


New Browser 4-18


6/64


7/64

viii



8/64

ix


PREFACE

A Guide to the Newton Toolkit

This book introduces the Newton Toolkit (NTK), a visual development

environment for Newton applications. Newton applications are written in

NewtonScript, an object-oriented language for programming the Newton

family of personal digital assistants (PDAs).

Note

Please remember that this manual is under development. Not allchapters are complete, and those that are may not be current. Please seethe release notes for the version of NTK you are using for the mostrecent technical information.

How to Use This Book

This guide provides both a tutorial introduction to developing applications in

NTK and a descriptive reference to NTK. If youre new to Newton

programming, you should start with this book, and then go on to the

NewtonScript ProgrammingLanguage and the Newton Programmers Guide.

n Follow the instructions in Chapter 1, Installation and Setup, to install theNewton Toolkit on your development systemand to connect a NewtonPDA on which you can test your application.

n Go through the tutorial in Chapter 2, A Quick Tour of NTK, tofamiliarize yourself with the basic approach to application development inNTK.

n Read the description in Chapter 3, The Newton Toolkit in Context, tosupplement your understanding of NTK. You might want to read Chapter3 in conjunction with the tutorial.

n Use Chapter 4, NTK Commands, as a reference, to look up informationas you need it.

Conventions

This book uses the following syntax conventions:


9/64

x


PREFACE

Changes Since Last Draft

This draft is a significant editorial departure from previous versions of theGuide to the Newton Toolkit. It is only slightly more complete technically.

Chapter 2, A Quick Tour of NTK, now includes a brief look at the inspector.

Chapter 3, The Newton Toolkit in Context, now describes the build

procedure.

Courier The Courier font represents material that is typedexactly as shown. Keywords, operators, and otherreserved elements appear in Courier. All code samples

are printed in Courier.italics Text in italics represents elements that can be replaced

by anything that matches their definition.

An ellipsis in a syntax description means that thepreceding element can be repeated one or more times.

An ellipsis in an example represents code not shown.


10/64

CHAPTER1

System Requirements 1-1

Alpha Draft 1.1. Preliminary, 1993 Apple Computer, Inc. 10/20/93

Installation and Setup

This chapter describes

n how to install the Newton Toolkit (NTK) on a Macintosh computer

n how to establish communication between the development system and a NewtonPDA through the Newton serial port.

System Requirements

Table 1-1 lists the hardware and software requirements for operating the Newton Toolkit.

Table 1-1 Hardware and Software Requirements

Note:

Downloading to a Newton PDA also requires one free serial port on the

Macintosh.

Installing NTK Software

To install NTK software from disks:

Recommended Minimum

Macintosh Quadra 68030-based Macintosh

Available RAM 8 megabytes 8 megabytes

Operating System System 7.1.xor higher

System 7.0with system Tune-up

System Settings 32-bit mode 32-bit mode


11/64

CHAPTER 1


1-2 Installing NTK Software

Alpha Draft 1.1. Preliminary,. 1993 Apple Computer, Inc. 10/20/93

1. Create a New folder on the volume where you want NTK to reside and name the newfolder. (Suggested name is NTK, thats how well refer to it in these instructions.)

2. Insert Diskette entitled Newton Toolkit.

3. Copy the entire contents of the diskette to the new NTK folder on your hard disk.This diskette contains a Release Notes file, the Teach Text application needed to readthe Release Notes, a compressed package file (Newton Toolkit Programs.PKG) and theApplelink Compression Utility.

4. Double-click on the Release Notes file to see if there are any last minute instructions.

5. Double-click on the Newton Toolkit Programs package file you have just moved to thenew NTK folder on your hard disk. The Applelink Compression Utility will belaunched and will list the contents of the package file. The package file contains thefollowing files:

n Apple Modem Tool

n AppleTalk ADSP Tool

n GlobalData file

n MessagePad file

n Newton Toolkit, the application file

n A suitcase file containing Newton Toolkit fonts

n NTK Definition file.

6. Using the Compression Utilities dialog box, choose the new NTK folder you createdin step one as the destination for the decompressed files and click OK. The files aredecompressed and copied to your new NTK folder.

7. Open the new NTK folder and drag the Apple Modem Tool, the AppleTalk ADSPTool, and Newton Toolkit font files to your System Folder on the hard disk. Leave theSystem Folder closed when copying the extensions and respond OK to let the system

place the extension and font files where they belong.8. Within the new NTK folder you have created, create another new folder and name it

Platforms. This folder MUST be within the same folder and at the same directorylevel as the NTK application. Drag the MessagePad file into this folder.

9. The GlobalData file is initially empty. You can add data to it (refer to GlobalData onpage 3-14 for a discussion.) If you use the GlobalData file, it must be in the samefolder as the NTK application.

10. The NTK Defnition file contains a list of all the compile-time constants and functionsthat have been precompiled into NTK. It is for information only and can be putanywhere.

11. Insert and copy the entire contents of Disk 2 entitled Newton Toolkit, Samples to

the new NTK folder on your hard disk. Disk 2 contains the Sample code folder,containing sample application project folders and a sample resources file.


12/64

CHAPTER 1


Communicating With a Newton From NTK 1-3


Communicating With a Newton From NTK

NTK is self-contained and can operate independently of a Newton. You can lay out,

code, and build an applicationpackage in the development system alone. To run your

application, however, you must establish a connection with a Newton and download the

package.

You can make a direct serial connection between your Newton and Macintosh. Once

youve established a connection, you install a small application, the Toolkit App, on the

Newton. The Toolkit App manages subsequent installation of NTK packages and

supports the inspector, an interactive debugger that lets you modify applications from

NTK while theyre running on the Newton.

A Newton with a connection to a Macintosh, the Toolkit App installed, and the inspector

open is a tethered Newton.

Connecting a Newton to a Macintosh Computer

You can connect your development system to a Newton with a null modem cable, that is,

a serial cable in which pins 2 and 3 are crossed over (pin 2 on the Macintosh end

connects to pin 3 on the Newton end of the cable; pin 3 on the Macintosh end connects to

pin 2 on the Newton end). This cable is also known as a direct serial cable and is often

sold as a printer cable. You can use Apple cable model M0197, part number 590-0552.

You install the cable between the serial connector on the Newton and one of the serial

ports on the Macintosh.

Note

Make sure that no other piece of Macintosh software is using the sameserial port.

The Apple Modem Tool extension, installed in your System Folder during NTK

installation, supports the connection.

Installing the NTK Toolkit App

This section describes how to install the Toolkit App on a Newton with a serial

connection to one of the built-in serial ports on the Macintosh computer.

On the Macintosh computer:1. Start NTK.

2. Dismiss the open-file dialog box by clicking Cancel.

3. Choose Install Toolkit App from the Project menu.

NTK reports that its waiting for a Newton response.

On the Newton


13/64

CHAPTER 1


1-4 Troubleshooting


4. Open the Extras drawer, and then tap the Connection icon.

A pop-up view opens on the Newton screen.

5. Tap the item labeled Macintosh serial.

6. Tap the Connect button.The PDA displays a dialog stating that the Connection application is waiting for aresponse. In a few seconds, the dialog disappears, and the Toolkit icon appears in theExtras Drawer. NTK Toolkit App installation is complete.

Connecting the Inspector

On the Macintosh computer:

1. Choose Connect Inspector from the Window menu.

On the Newton

2. Open the Toolkit App by tapping its icon in the Extras drawer.

3. Tap the Connect Inspector button.

The Toolkit App reports that its opening the inspector.

Note:

The Connect Inspector command opens a connection with the Newtonand opens the inspector window if it isnt already open. The OpenInspector item opens and closes the inspector window itself. Openingthe inspector window doesnt open a connection, but closing theinspector window closes the connection.

When the inspector is connected, its window opens on the Macintosh screen.

4. Type2 + 1;

and press Enter.

The inspector displays a reference and the value of the statement, 3.

Troubleshooting

If you encounter difficulties with NTK, try the following:

n Check for 32-bit addressing. Your Macintosh must be in 32-bit mode. Use the Memory

control panel to set this mode.n If you are using a Powerbook or Powerbook Duo, check that the modem is set to

External Modem.

n If you are using a Powerbook Duo, ensure that theNTK Settings command hasselected the Printer-Modem option.

n Read the Release Notes.


14/64

CHAPTER2

Starting Up NTK 2-1


A Quick Tour of NTK

This chapter is a tutorial that outlines the Newton application development process and

introduces the major components of NTK.You can follow the tutorial to create, build, and test a simple application named Hello.

The tutorial illustrates these steps:

n Starting up NTK

n Setting up an application project

n Laying out the applications visual interface

n Defining the behavior of the various elements and establishing access among views

n Building an application package and downloading it to a PDA

n Inspecting the application during runtime

Note

This tutorial assumes that youre running NTK on a Macintoshcomputer with an open connection to a Newton PDA, as described inChapter 1, Installation and Setup.

Starting Up NTK

1. Double-click the Newton Toolkit application icon to start NTK.

NTK displays its startup screen followed by a file-open dialog box.

2. For this tutorial, click Cancel.


15/64

CHAPTER 2

A Quick Tour of NTK

2-2 Setting Up a New Project


Setting Up a New Project

You build a Newton application from a collection of files, which you administer through

a project file. The first step in creating an application is to start a project file.

1. Choose New Project from the Project menu.

NTK presents the standard file-save dialog box.

2. Create a new folder named hellofolder, and change the default project name tohelloproject.

3. Click Save.

NTK displays the blank project window.

4. Choose Settings from the Project menu.

NTK displays the Project Settings dialog box.

You use the Settings command to specify the information NTK needs to build yourapplication package. For a description of the Project Settings dialog box, see thedescription of the Settings command in Chapter 4, Command Reference.

5. Change the application name from ChangeMe toHello.


16/64

CHAPTER 2

A Quick Tour of NTK

Starting a Base View and Adding It to the Project 2-3


When you install the finished application on a PDA, this name appears beneath theapplications icon in the Extras drawer.

6. Change the symbol to Hello:TUT.

7. Change the package name to Hello:TUT.

8. Click OK.

Starting a Base View and Adding It to the Project

NTK supplies a graphical editor for arranging the visual elements of your applications

user interface.

You typically start with the application base view, the screen image that appears when

you start the application. (The application base view is the ancestor of all other views in

an application. It is the hub of the application, both visually and structurally.)

1. Choose New Layout from the File menu.

NTK opens a new, blank-screen layout window and displays a palette of applicationcomponents.

The default layout window represents the screen of the Newton MessagePad.

The NTK graphical editor follows the basic Macintosh interface conventions. For moreinformation, see the section on layout tools in Chapter 3, NTK in Context.

2. Move the pointer over the buttons on the palette.


17/64

CHAPTER 2

A Quick Tour of NTK

2-4 Starting a Base View and Adding It to the Project


Note that the item visible in the Selection menu changes as you move the pointer overthe buttons. The name of each element appears when the pointer is over the elementsbutton.

3. Press and hold the mouse with the pointer on the Selection pop-up menu.

NTK displays the names of all the system-defined components on the palette. You canselect elements either by clicking their buttons or by choosing them in the Selectionpop-up menu.

4. Using either the buttons or the Selection pop-up menu, select the protoApp template,shown here.

The protoApp template defines a view that can contain other views and that includesa few basic application features: a title bar, a status bar, and a close box.

Most applications use either the protoApp template or theclView view class for the

base view. (For a description of the system-defined view classes and protos, see thechapter View Basics in the Newton Programmers Guide.)

5. Draw the base layout view, positioning it approximately as shown here.

This tutorial leaves an unlikely border to emphasize the presence of the base view.

NTK labels your new layout view protoApp, using the name of the proto templatefrom which it was constructed.

6. Choose Template Info from the Special Menu.


18/64

CHAPTER 2

A Quick Tour of NTK

Laying Out a View 2-5


NTK displays the Template Info dialog box, which displays the name of a view and itsaccessibility from other views.

You must supply a unique name for the application base view and for all views thatare accessed from other views.

7. Type in the name baseView, and then click OK.

8. To save the layout file that holds the base view, choose Save As from the File menu,type the name mainHello, and then click Save.

9. Choose Add Window from the Project Menu.

NTK adds mainHello to the project file.

10. Click the title bar of the project window to see the list of files in the project, which atthis point includes only the file mainHello.

By default, NTK designates the first layout file you add to a project the main layout

file, that is, the file containing the base view. Once youve added more views to theproject file, you can change the main layout file through the Project menu.

Laying Out a View

You build your user interface by laying out other views on your base view.

This section of the tutorial adds system-defined componentstemplates, view classes,

and the special linked subview elementfrom the NTK palette. You can also define your

own templates and add them to the palette, as described in Defining Your Own Proto

Template beginning on page 2-15.

1. Activate the view window, now titled mainHello, by clicking its title bar.

2. Using either the buttons or the Selection pop-up menu, selectprotoLabelInputLine from the palette.


19/64

CHAPTER 2

A Quick Tour of NTK

2-6 Customizing a View


3. Draw out a rectangle inside the base view, imitating the size and location shown here.

4. To see what the view will look like on the Newton screen, choose Preview from theLayout menu.

You can toggle between layout mode and preview mode with the Preview command(Command-Y).

You can build your project into a package at almost any point after youve established

your base view. The following three sections add more features to the Hello application

while illustrating how to use the NTK browser and other tools. If you prefer, you can

skip now to Building and Downloading a Package beginning on page 2-17 to build the

application as it is, download it to a tethered Newton, and run it.

Customizing a View

Every time you create a new view, NTK creates a view template, a frame containing the

named slots that define the structure and behavior of the view. All of the view templates

for a single layout window are stored in a single layout file.

You can look at and edit view templates with NTKs browser. The browser displays a list

of views and a list of slots within the the selected view. When you select a slot for

editing, the browser invokes a slot editor of the appropriate type.

Editing a Slot

This section illustrates how to edit a slot.

You can change the title that appears on your applications base view by editing the

title slot in the base view template.

1. Select the base view in the main layout window by clicking within the base view butoutside the text-input view.


20/64

CHAPTER 2

A Quick Tour of NTK

Customizing a View 2-7


2. Choose New Browser from the Window menu.

NTK displays a browser window for the base view, as illustrated in Figure 1-1.

Figure 1-1 A browser window.

The template list shows the base view itself and any views laid out within the baseview. The slot list shows the slots that have been defined for the view thats selected inthe template list.

By default, the first item in each list is selected when the window first appears.

3. Double-click the title slot in the slot list to open that slot for editing.

NTK displays the current contents of the title slot, Application, in the editing area.

When you open a slot for editing, NTK invokes the editor appropriate to the contentsof that slot. You edit the title slot with a simple text editor.

4. Select the default text and change it to Hello,World.

5. Apply the change by clicking the check mark in the lower-left corner of the browserwindow.

To apply a change through the keyboard, press Command-E.

slot listtemplate

list

slot editor

area

Cancel

Apply


21/64

CHAPTER 2

A Quick Tour of NTK

2-8 Customizing a View


If the layout window is still in preview mode, you can see the name change as soon asyou apply the change. If the layout window is in layout mode, activate the layoutwindow and then choose Preview from the Layout menu to see the label change.

6. Save the layout file by choosing Save from the File menu.

Note that you cannot save the contents of a browser window. Saving from thebrowser saves the layout file for the view youre editing.

Adding a Slot

The slot list in the browser window shows the slots that youve defined for a view. You

can add system-defined slots to a view through the pop-up menus labeled Specific,

Methods, and Attributes (below the slot list).

n The Specific list contains the optional slots in the proto template on which the currentview template is based. Slots in the Specific list may contain either attributes ormethods.

n The Method list contains method slots common to a subset of the proto templates.

n The Attributes list contains attribute slots common to a subset of the proto templates.

You can also define and add your own slots by choosing New Slot from the Special

menu, as described in Chapter 4, NTK Commands.

In this section of the tutorial, you add a label to the applications text-input area by

adding the system-defined label slot to the view template.

1. If the browser window isnt active, click its title bar to activate it.2. Select -protoLabelInputLine from the view list by clicking it.

The broswer adjusts the slot list to show the slots defined for that view.

3. Choose Label from the Specific pop-up menu.

NTK invokes the text editor and displays the default label, Label. It adds thelabelslot to the slot list.


22/64

CHAPTER 2

A Quick Tour of NTK

Adding a Linked View 2-9


4. Replace the default label with the text

My Message

5. Apply the change by clicking the Apply checkmark or by choosing Apply from theSpecial menu.

Again, if the layout window is in preview mode, you can see the change immediately.

6. Save the layout file by choosing Save from the File menu.

Adding a Linked View

Most applications include at least one linked view, that is, a view that you lay outseparately and link into the application base view. You might lay out a dialog box, for

example, as a linked view. You use linked views to break up the application into logical

modules and to keep the base view from becoming too cluttered during application

development.

You make a linked view available to the application by linking it to the base view

through a system-defined component called a LinkedSubview. In this tutorial, you

make it available to the user by adding to the base view a button that, when pressed,

passes an open message to the linked view.

Laying Out a Linked ViewIn this section of the tutorial, you lay out a linked view containing a screen message to be

displayed when the user presses a button.

1. Choose New Layout from the NTK File menu.

2. Choose Save As from the File menu, and save the view with the name floatermessage1.


23/64

CHAPTER 2

A Quick Tour of NTK

2-10 Adding a Linked View


3. Choose Add Window from the Project menu to add floatermessage1 to theproject list.

Note that Add Window adds the active view to the project list; Add File displays thefile-select dialog box and allows you to add a file from anywhere on the desktop.

4. Select protoFloatNGo from the palette.

You build a linked view the same way you build the base view, that is, by firstcreating the topmost view and then laying out the view elements within it. For thistutorial, youll use the protoFloatNGo proto, which defines a floating view with aclose box.

5. Draw the view, positioning it approximately as shown here.

The rectangle you specify in this step defines the size and location of the linked view.

6. Choose Template Info from the Special menu, name the view MyFloatNGo, and clickOK.

7. Select protoStaticText from the palette.


24/64

CHAPTER 2

A Quick Tour of NTK



8. Lay out the text view within the topmost view approximately as shown here.

This rectangle defines the location of the static text message within the linked view.

9. Using the Template Info dialog box, name the view myFloater1Message

10. With themyFloater1Message view still selected, choose New Browser from theWindow menu to open a browser window.

NTK displays a new browser.

Note that the view list contains only the view that was selected when you opened thebrowser window. (If the view had any descendants, those descendants would alsoappear in the list.)

11. Double-click on the slotnametext to open the slot for editing.

The browser displays the default text, Static Text.

12. Select the default text and replace it with your own message. For example,

Hello, world, from a linked view.

13. Apply the change.

14. Save the file.


25/64

CHAPTER 2

A Quick Tour of NTK

2-12 Adding a Linked View


Linking a View

To make the linked view accessible to the application, you add the LinkedSubview

component to the applications base view. You name the linking view and allow access to

it (also known as declaring it) through the Template Info command. Then you use theLink Layout command to establish the link.

1. Activate the main layout window (main Hello) by clicking its title bar.

2. Select LinkedSubview from the palette.

3. Lay out the linked subview approximately as shown here.

Note that the specific placement of the linked subview doesnt matter. When the PDAbuilds the linked view, it uses the specification from the linked views template (inthis case, MyFloatNGo).

4. Open the Template Info dialog box by choosing Template Info from the Special menu(or by pressing Command-I).

5. Type in the name floaterLink, but dont click OK yet.

6. Click the box labeled Allow Access From.

IffloaterLink had more ancestors, they would appear in the popup list. In thisexample, only baseView is available.


26/64

CHAPTER 2

A Quick Tour of NTK



Allowing access to a view is also known as declaring the view. This example declaresthe floaterLink view to the baseView view.

7. Click OK.

8. With thefloaterLink view still selected, choose Link Layout from the File menu.

NTK displays the file-select dialog box.

9. Select the filename floater message 1, and then click Open.

The main Hello layout window now reflects that floaterLink is linked to thelinked view floater message 1.

Adding a Button That Displays the View

To incorporate the floater view into the applications interface, this tutorial adds a button

to the applications base view and sets up the button to send an open message to the

linked view when pressed.

1. With the main Hello window still active, chooseprotoTextButton from the palette.

2. Draw the button, positioning it approximately as shown here.

The rectangle you draw in this step determines the size, shape, and position of thebutton on the Newton screen.

3. Use Template Info to name the new view showFloaterButton.

4. Activate the main Hello browser window by clicking its title bar.

5. Select -protoTextButton:showFloaterButton from the view list, and thendouble-click the ButtonClickScript slot to open it for editing.

NTK invokes the text editor and displays a skeletal function statement.


27/64

CHAPTER 2

A Quick Tour of NTK

2-14 Defining Your Own Proto Template


6. Insert an instruction to send an open message to the floaterlink view, so that thetext reads:func()

begin

floaterlink:open()end


8. Double-click the slotname text to open the slot for editing.

This slot specifies the text on the button itself.

9. Change the default button text to Show Linked View.


11. Save the file.

Defining Your Own Proto Template

You can lay out your own proto templates and add them to the NTK palette.

This tutorial creates a user proto templatethat is, a template defined by you, not built

into the Newton PDAthat contains three radio buttons. If you needed the view in only

one place, youd likely lay it out as a standard layout file. Defining a layout as a proto,

however, opens up two opportunities:

n You can use the same template in different views or applications.

n Your application can use the proto to create views dynamically as needed.

Laying Out a Proto and Adding It to the Palette

1. Choose New Proto Template from the NTK File menu to open a proto layout window.

You set up a proto template the same way you set up any other layout file: youestablish the topmost view and place other elements within it.

2. Select protoRadioCluster from the palette.

The protoRadioCluster proto provides a layout view for radio buttons.


28/64

CHAPTER 2

A Quick Tour of NTK

Defining Your Own Proto Template 2-15


3. Draw the layout view approximately as shown here.

4. Select protoRadioButton from the palette.

This proto defines a single, labeled radio button.

5. Draw a wide, flat rectangle within the cluster view.

6. Make two duplicates of the radio button (with the new radio button selected, chooseDuplicate twice from the Edit menu), and then position the buttons approximately asshown here.

7. Use the Template Info command to name the layout view myRadioButtons.

8. Save the layout file as myRadioButtonsProto.


29/64

CHAPTER 2

A Quick Tour of NTK

2-16 Building and Downloading a Package


Important:

Use only alphanumeric characters in proto names. Do not use spaces,punctuation, or special characters.

9. Choose Add Window from the Project menu.

NTK adds the file myRadioButtonsProto to the project.

NTK also adds myRadioButtonsProto to the User pop-up menu and makes thatmenu available.

Using Your Proto Template

Once youve saved your proto template and added it to the project, NTK gives you

access to it through the palette.

1. Activate the main Hello window.

2. Click the User button to activate the user template pop-up menu. Choose

myRadioButtonProto from the pop-up menu.

3. Drag out a view in the lower part of the base view.

4. Save the layout file.

Building and Downloading a Package

At almost any point in the development process, you can build your application files

into a package, which you can download and run on a Newton PDA.


30/64

CHAPTER 2

A Quick Tour of NTK

Using the Inspector 2-17


Note

To download, you must have established communication between thedevelopment system and the PDA and installed the Toolkit App on thePDA. These steps are described in Chapter 1, Installation and Setup.

1. Choose Save All from the File menu.

2. Choose Build Package from the Project menu.

NTK builds the package and places it in the project folder.

NTK always creates the package in a file calledprojectname.pkg.

3. Choose Download Package from the Project menu.

The Macintosh reports that its waiting for the PDA.

If the inspector is connected, the Toolkit App handles the download automatically.

4. If the inspector is not connected

n Open the Toolkit App icon in the Extras drawer on the PDA.

The Toolkit App view pops up.

n Tap the Download Package button.

The PDA displays a message while the download proceeds.

5. When downloading is finished (the Hello icon appears in the Extras drawer), open theapplication by tapping its icon.

Using the Inspector

The inspector is an interactive debugger that lets you browse the Newton object storage

system and execute NewtonScript code on the PDA. The debugging functions are

described in the chapter on debugging in the Newton Programmers Guide.

Note

To use the inspector, you must have established a connection betweenthe development system and the PDA and installed the Toolkit App onthe PDA. These steps are described in Chapter 1, Installation andSetup.

Connecting the Inspector

On the Macintosh:

1. Choose Connect Inspector from the Window menu.The Macintosh reports that its waiting for the PDA.

On the PDA:

2. Open the Toolkit App by tapping its icon in the Extras drawer.

3. Tap the Connect Inspector button.

The Toolkit App reports that its opening the inspector.


31/64

CHAPTER 2

A Quick Tour of NTK

2-18 Using the Inspector


The inspector window opens on the Macintosh.

Executing Commands

The inspector processes your keystrokes only when you explicitly request it by selectingand entering text. If no text is explicitly selected, the inspector processes the current line.

The code is compiled on the Macintosh computer and sent to the Newton PDA, where it

is executed. Results are displayed on the Macintosh screen.

1. In the inspector window, type these two lines

x := 1/3;

x;

2. Select both lines and press Enter.

The inspector displays the value ofx, 0.333333.

You can enter and execute any valid NewtonScript code. The inspector prints to thescreen a reference number and the value of the last statement.

Looking at a Frame

This tutorial looks at the Hello application developed earlier in this chapter. It assumes

you have built and downloaded a package as described in Building and Downloading a

Package beginning on page 2-17 and that you have not changed the default NTK

Preferences settings.

1. Open the Hello application on the PDA by tapping its icon.

2. Open the floating window by tapping the Show Linked View button.

3. Type in the inspector window

debug("floaterLink")

4. Press Enter.

The inspector displays the view for the floaterLink template.

#440DBE9 {_Parent: {_Parent: {#4407939},

_proto: {#600044BD},

viewCObject: 0x1108C45,

floaterlink: ,

viewclipper: 17861715,

base: ,

viewFlags: 5},

_proto: {viewBounds: {#600047BD},

stepChildren: [#600047FD],

_proto: {#2D3},

debug: "floaterLink",

preallocatedContext: floaterlink},


32/64

CHAPTER 2

A Quick Tour of NTK

Using the Inspector 2-19


viewCObject: 0x1108E20,

base: ,

viewFlags: 65}

5. Close the floater window on the PDA.

6. Put the insertion point anywhere in the line debug("floaterLink") and thenpress Enter.

The inspector responds NIL, because there is no view.


33/64

CHAPTER3

Development Cycle Overview 3-1


Using the Newton Toolkit

NTK is an integrated environment for developing applications for the Newton PDA.

This chapter describes how you use NTK for

n managing a project

n laying out and programming an application

n building and downloading an executable package

n debugging

Development Cycle Overview

The Newton PDA environment is a graphical one, in which the user works with visualelements on the screen to accomplish a wide range of tasks.

NTK supplies a graphical editor and a palette of application components that you can

use to lay out your interface. Each element on the screen is a view, that is, a visible

manifestation of a frame. Each view is built from a template, that is, a frame that

describes a view. (A frame is the basic data structure used in Newton programming, as

described in The NewtonScript Programming Language.) Like any other frame, a view

template contains named entries called slots.

You define a views characteristics and behavior by specifying the contents of the slots in

its template. NTK provides a browser, which lets you search through the templates and

edit them.

Once youve programmed your application, you use NTK to build a package, that is, the

application in a form that can be downloaded to the Newton PDA.

NTK also includes an interactive debugger, the inspector, that lets you study and alter

your application while its running.


34/64

CHAPTER 3


3-2 Project Management


Project Management

A NewtonScript application is built from a collection of files:

n layoutfiles, which contain the frames you define in NTKs graphical editorn the project data file, which contains your applications installation and shutdown

scripts and any expressions youve defined for the build

n resource files, which contain resources (pictures, sounds, and fonts)

You organize and manage the various component files through a project file, which

contains a list of the files in a project.

When you open the project file, NTK displays the project window,which lists the files

currently included in the application. Figure 2-1 illustrates a project window with one

view selected.

Figure 2-1 The project window, with the main layout file selected

You create a project file through the New Project item in the Project menu. You add files

to the project through the Add Window and Add File commands. You must also specify

a collection of project specifications through the Settings command. Figure 2-2 illustrates

the Project Settings dialog box.


35/64

CHAPTER 3


Project Management 3-3


Figure 2-2 The Project Settings dialog box

The best policy is to establish a unique application name, application symbol, and

package name for each project. The name is the text that appears under the applications

icon in the Extras drawer. The symbol is the alphanumeric string by which the

application identifies itself to the Newton root view. The package name is the internal

name of the package, that is, the package name thats used on the PDA.

Note:

The symbol you specify in Project Settings is the symbol that NTK placesin the package during the build. It allows the PDA to recognize and runyour application. To register your symbol for system services like Findand Intelligent Assist, you must define a slot named appSymbol in theapplication base view template and set its value to this same uniquesymbol name. For an explanation of registering for system services, seeMiscellaneous System Services in the Newton Programmers Guide.

Apple recommends that you build your application symbols and package names from

your companys registered signature and your own application identifiers, using this

convention:

applicationID:signature.

A developer with the signature SURF, for example, might identify a checkbook

application with the symbol and package name check:SURF.

For more information on symbol and package names and descriptions of the other fields

in Project Settings, see the description of the Settings command in Chapter 4, NTK

Commands.


36/64

CHAPTER 3


3-4 Laying Out Views


You build an executable package with the Build Package command. You can download

the package to a tethered Newton through the Download Package command.

(Instructions for setting up a tethered Newton appear in Chapter 1, Installation and

Setup.)

You can adjust your own NTK environment through the Preferences item in the Editmenu. Figure 2-3 illustrates the Toolkit Preferences dialog box. For a detailed description

of the fields, see the description of the Preferences command in Chapter 4, NTK

Commands.

Figure 2-3 The Toolkit Preferences dialog box

Laying Out Views

You use NTKs graphical editor to lay out views into a window the size and shape of the

Newton screen.

Figure 2-4 illustrates the layout window and the palette of components.


37/64

CHAPTER 3


Laying Out Views 3-5


Figure 2-4 Layout window and palette

The editor saves the views you lay out in a layout file, which contains a hierarchy of

views. Each layout file must have a single topmost view, which contains all other views

in the layout. The topmost view can contain any number of child views, whichthemselves can contain any number of child views, and so on.

You build an application by creating views from the palette of components. You create a

view by choosing a component and then drawing out a view in the window. The palette

includes buttons and pop-up menus that let you add

n view classes, the basic building blocks of view templates

The view class clParagraphView, for example, is the generic text view, used forstatic text or for text in an edit view.

n prototype templates, constructed from the view classes

The prototype templates, or protos, are built into the Newton ROM and provideready-to-use elements like radio buttons and slide controls.

n user protos, that is, prototype templates you define yourself

User protos can be based on view classes, system protos, or other user protos.

n linked subviews, an NTK device for linking in views laid out in separate layout files.

For descriptions of view classes and prototype templates, see the chapters View Basics

and Working With Proto Templates in the Newton Programmers Guide.

Selection

pop-up menuUser-defined

proto pop-up menu

view alignment

primitive view

classes

linked

subview


38/64

CHAPTER 3




The view alignment buttons align selected views as illustrated on the buttons.

You can break up your application into logical modules and then link the files together

through linked subviews. Using multiple layout windows reduces the clutter in your

layout windows as you add more complexity to your application.

The topmost view is usually a container view, that is, a view that serves primarily as a

container for other views. The view class clView is the generic container view.

Theview that opens when the user taps an applications icon is the application base

view. The application base view is the ancestor of all other views in the application, and

it is the conduit for communication among views.

The proto protoApp supplies a functional application base view. It is a container view

with a title bar, a status bar, and close box.

Drawing, Resizing, and Moving Views

The graphical editor follows the basic Macintosh user interface conventions.

Drawing a View

To add a view to your application, you first select a the view you want from the palette

and then draw out the view in the layout window, using the click-and-drag model.

You can select a component from the palette by either clicking one of the view buttons or

selecting an entry from one of the two pop-up menus. The selection menu near the top of

the palette contains the system-defined view classes and proto templates. The User

menu contains any proto templates youve created and added to the project. You can

activate either the selection list or the user list by clicking the selection button (the button

with an arrow on it) or the user button (the button with the letter U on it).

Once youve chosen a component, move the cursor to the layout window. To draw a

view in the window:

1. Place the cursor where you want any corner of the view to appear.

2. Press and hold the mouse button while you move the cursor to the opposite corner.

3. Release the mouse button.

The rectangle youve defined on the screen marks the location of the view.

Figure 2-5 illustrates a layout window just after its topmost view has been drawn.


39/64

CHAPTER 3


Laying Out Views 3-7


Figure 2-5 A layout window with a layout view in place

The label in the upper-left corner of the view shows the view class or proto template on

which the view is based. After youve named a view, its name appears instead.

The small boxes in the corners of the view indicate that the view is selected. The selected

view is the target of whatever view-editing instructions you make through the mouse or

keyboard. You can select a different view by clicking it. To select multiple views, hold

down the Shift key while clicking

Resizing a View

You can resize a view with either the mouse or the keyboard.

Moving and Aligning Views

Previewing

You ordinarily draw views with the graphical editor in layout mode, in which NTK

displays the rectangular extents of the views and their names. You can see a closer


40/64

CHAPTER 3




approximation of how the views will look on the Newton screen by choosing Preview

from the Layout menu.

Figure 2-6 illustrates a simple view in layout mode and preview mode.

Figure 2-6 The layout window in layout and preview modes

Declaring Views

You declare views through the Template Info command in the Special menu.

Linking Multiple Layouts

You can organize your application into logical modules by laying it out in multiple

layout windows. You link the individual layouts to the base view by laying out a small

reference view on the base view, declaring it to the base view, and then linking it to the

other layout file.

layout mode preview mode


41/64

CHAPTER 3


The Browser 3-9


Creating User Proto Templates

You can use the New Proto command in the Project menu to lay out your own proto

template. You save the layout in a separate file and add it to the project. Then you can

reach the template through the User proto pop-up menu on the palette.

Creating Print Format Templates

The Browser

When you draw out a view, NTK creates a template that corresponds to the view it

displays. To customize the view template, you use a browser and slot editor.

You can browse the entire set of templates currently present in an application or examine

a subset of the templates. When you select a particular template, the browser displays its

slots and their current values. You can select a particular slot and edit its values in a slot

editor. As you edit the slot, you change the template specification for a view that will be

created from it.

Figure 2-7 illustrates a template browser window with the viewFlags slot open for

editing.

Figure 2-7 A template browser with a pending change in the viewFlags slot


42/64

CHAPTER 3


3-10 Building a Project


A template browser window is composed of two lists areas and one edit area. The top

left window is the view template list. The top right area is the slot list. The bottom area is

the slot editor area.

In a browser, you select and work with one template at a time; and within each template,

one slot at a time. The value of a each slot can be defined independently of the others.

You can add new slots to a template by selecting one from a list of built-in optional slots,

or you can create a new user-slot.

NTK slot editors vary according to the type of data contained in a given slot. Many slots

accept only a single value; others, like a title slot, require a character string. Slot editors

for these simple slots are themselves simple. Other slots and their editors are more

complex. For example, the optional ViewEffect slot, common to all view templates, is

a large slot containing many variablesits slot editor makes it easy to do things like

setting up graphical effects to accompany the opening of a view as it is displayed on the

screen.

An application may require a large number of views and view templates. Moreover, the

views may be laid out on more than one layout screen and nested in a number of parent/

child hierarchies.

NTK lets you choose how much of this overall complexity to display in a single browser.

If you start at the topmost view, one browser can display all of the views in a template

file. If you open a browser with a child view selected, you can see only that view and the

views below it in the hierarchy. For example, if you first selected the Radio Cluster view

in Figure 2-7, and then opened a browser, you could browse and edit the Radio Cluster

template and its child views, the three radio buttons.

Building a Project

You build a project by choosing Build Package from the Project menu.

NTK processes the project in this order:

n the print templates

n the project data file

n layout files (starting at the main layout and recursively processing the view hierarchy)

When NTK reaches a view thats based on a user proto, it processes the proto first andthen the view.


43/64

CHAPTER 3


Building a Project 3-11


n unprocessed user proto templates

Do not rely on the order of processing print templates; you can, however, rely on the

order of processing layouts.

NTK processes templates in this order:

n any protos referenced in the template

n the before script if its present

n the layout, starting at the main layout and then recursively processing all children inorder

n the after script if its present

BeforeScript and AfterScript Slots

Before processing a view template, NTK looks for a slot with the name BeforeScript

and executes it if its present. After processing the template, NTK looks for and executes

a slot with the name AfterScript.

The before and after scripts give you a place to execute code specific to a view. You can

use the before script to define compile-time functions and data, the same way you use

the project data file described in the next section.

The code in the before and after scripts is not part of the final applicationyou reference

it through evaluate slots elsewhere in the view template. Note that the beforeScript

and afterScript slots exist at compile time but not at run time.

The view context is available to the after script through the variablethisView, which is

a reference to the view template. You can use thisView to add slots or change the value

of exisitng slots. This code in the after script, for example, would conditionally add an

extra debug slot:

if (debugOn) then thisView.debugInfo := ;

This code creates the extra slot only when the Debug Build option is set. (Chapter 4,

NTK Commands, documents the Debug Build option in the description of the Settings

command.)

Warning

The thisView variable gives your after script access to any slot in aview. Its an easy way to introduce debilitating bugs.

You can create before and after scripts for any view through New Slot in the Special

menu. Create them as evaluate slots with the namesBeforeScript

andAfterScript

.

Project Data

The project data file is an adjunct to your projectits a way to make declarations

available to your project at compile time. Its also the vehicle for defining install and

remove scripts.


44/64

CHAPTER 3


3-12 Building a Project


You can place in the project data file

n an InstallScript, which is run when your package is installed in the PDA

n a RemoveScript, which is run when your package is removed

n other NewtonScript code

This example illustrates a project data file.

InstallScript := func(partFrame)

begin

//install preferences template in preferences global

partFrame.prefsTemplate :=

EnsureInternal(partFrame.theForm.PT_PreeferPrefsItem);

AddArraySlot(preferences,partFrame.prefsTemplate);

//if Prefs is open, force update

if getroot().preferenceRoll.viewCObject then

getroot().preferenceRoll:RedoChildren();//install formula template in formulaList global

partFrame.formulaTemplate :=

EnsureInternal(partFrame.theForm.PT_PreeferFormulaItem);

AddArraySlot(formulaList,partFrame.formulaTemplate);

//if Formulas is open, force update

if getroot().formulaRoll.viewCObject then

getroot().formulaRoll:RedoChildren();

end;

RemoveScript := func(partFrame)

begin//remove preferences template from preferences global

SetRemove(preferences,partFrame.prefsTemplate);

//if Prefs is open, force update

if getroot().preferenceRoll.viewCObject then

getroot().preferenceRoll:RedoChildren();

//remove formula template from formulaList global

SetRemove(formulaList,partFrame.formulaTemplate);

//if Formulas is open, force update

if getroot().formulaRoll.viewCObject then

getroot().formulaRoll:RedoChildren();end;

constant AppSymbol := '|Hello:TUT|;

constant PackageName := "Hello:TUT";


45/64

CHAPTER 3


Building a Project 3-13


To access a value from the project data file in a run-time script, use it in an evaluate slot.

InstallScript

NTK looks in the project data file for the InstallScript, which it puts into the package.

The InstallScript runs when your package is installed in the Newton PDA, typically

when the card containing it is inserted or when NTK downloads the application package.

You use your InstallScript to register your application with system services such as Find

and Intelligent Assist.

Note that the InstallScript for every application on a card is run when the card is

inserted. To avoid competing with other applications, therefore, you should not include

any user interface code in the InstallScript.The InstallScript is called with this syntax:

InstallScript(partFrame)

partFrame The part frame for your application. This frame has a slot namedtheForm, which contains a reference to your applications basetemplate. You can access information in your application throughthis slot.

Note that the InstallScript executes before your base view is created.

RemoveScript

NTK looks in the project data file for the RemoveScript, which it puts into the package.

The RemoveScript runs when your application is removed from the Newton PDA,

ordinarily when the card containing it is removed. It is also run when you remove a

package through NTK and when the user removes your application through Memory

Preferences.

You use your RemoveScript to clean up anything left in the system by the InstallScript.

You should unregister your application from the system-services frames, if it was

registered. You must remove any globals created in the InstallScript.

The RemoveScript is called with this syntax:

RemoveScript(partFrame)

partFrame The part frame for your application.

Note that the RemoveScript runs after your applications card has been removed. The

theForm slot therefore contains an invalid reference.


46/64

CHAPTER 3


3-14 Debugging


NewtonScript Code

You can define constants and functions in the project data file with the constant andfunc statements, described in NewtonScript Programming Language.

You can assign a constant to any literal expression but not compound expressions ordynamically created objects.

GlobalData

The GlobalData file is an adjunct to NTK. You can place in it NewtonScript code that

you want available from any project.

The GlobalData file is compiled once each time NTK is opened. Code you place in

GlobalData is available during compile time to any project you build.

If the compiler encounters an error in GlobalData, it displays the error type, filename,and line number. When you dismiss the error dialog, NTK quits. The prudent course is

to develop code in the project data file and move it to GlobalData only when itsdebugged.

Debugging

The inspector is an interactive debugging environment that lets you study your

application while its executing and make changes dynamically.

The inspector window is the target of any print, write, and display commands

embedded in your application.


47/64

CHAPTER4

File Menu 4-1

Alpha Draft. Preliminary, 1993 Apple Computer, Inc. 10/8/93

NTK Commands

This chapter describes the commands available through NTKs menus.

File Menu

You use the File menu to create, save, print, and otherwise manipulate files.

New Layout

Opens a new layout window and creates an associated layout file.

New Proto TemplateOpens a new proto template layout window and creates an associated proto file.

You use this command to lay out your own proto templates, which you can add to the

layout palette. See for an illustration of how to create and use a proto

template.

New Print Format

Opens a new print-format layout window and creates an asssociated print-format file.

You use use this command to lay out print-format versions of your applications

templates. You can link the print-format versions with the screen-format versions, so thatwhen the user prints a view from the screen, the application uses the print format

instead of the screen format.


48/64

CHAPTER 4

NTK Commands

4-2 File Menu

Alpha Draft. Preliminary,. 1993 Apple Computer, Inc. 10/8/93

Open

Opens a saved layout file. The Open command displays the file-open dialog box, which

lets you select a file to open

You open a project file through the Project menu, and you open the inspector window

through the Windows menu.

Link Layout

Links the selected linked subview in the active layout window with the saved layout

that you specify through the standard file-select dialog box.

You use Link Layout to link a linked subview in a layout with a view that was laid out in

a separate layout window.

Close

Closes the active window and its associated file. Close can affect a layout file, a project

file, a browser window, or the inspector window.

If you close a window thats been edited since its file was last saved, NTK displays a

verification dialog box that gives you a chance to save changes before closing the

window.

Save

Saves the file associated with the active window. The saved file replaces the previously

saved file of the same name. The file remains open.

The Save command affects only the one active window, that is,

n the layout file for the active layout window,

n the layout file for the active browser window,

n the project file associated with an active project window, or

n the contents of the inspector window, if its active.

Save As

Saves a new copy of the file associated with the active window. The Save As commandopens a file-save dialog box, through which you specify the new name and location.

Save As changes the name of the active window and closes the file associated with the

windows previous name.

You use Save As to name or rename a layout window. Because the Save As command

displays the standard file-save dialog box, you can also use it to create a new folder.


49/64

CHAPTER 4

NTK Commands

File Menu 4-3


Save a Copy In

Saves a separate copy of a layout or Inspector file, with the name and location you

specify through the file-save dialog box. The Save a Copy In command does not change

the name or path of the active window and leaves its associated file open.

You use Save a Copy In to back up a file or to make a copy of a layout that you might

want to use in another application.

Save All

Saves all open layout files under the names already established. If youve not yet saved a

file associated with one of the windows, NTK prompts you for the necessary filenames.

Use Save All before each project build to ensure that the project files match all changes

youve made.

Revert

Restores the last saved version of the file associated with the active window. Any

changes youve made since the last save are discarded.

Page Setup

Opens the Page Setup dialog box, which lets you specify the paper size and printing

orientation for the active window.

Print One

Prints one copy of the file associated with the active window on the printer already

selected through the Chooser. This command prints without displaying the Print dialog

box for your verification.

Print

Prints the file associated with the active window.

When you choose Print, NTK displays the printing dialog box, which identifies the

selected printer and lets you verify or change the printing options.

Note

You must select Color/Grayscale in the printing dialog box to print alayout.


50/64

CHAPTER 4

NTK Commands

4-4 Edit Menu


Edit Menu

You use the Edit menu to manipulate the contents of a windowediting views in a

layout window, for example, or text in a browser window.

Undo

Cancels the last change made to a view in a layout window or to a slot in a browser

window. If, for example, youve just deleted a view from a layout, choosing Undo

restores the view. If youve just edited a slot in a template, Undo restores the previous

value of the slot.

If NTK cannot undo the last operation, this command reads Cant Undo and is disabled.

Cut

Deletes the current selection in the active window and places it on the Clipboard. You

can then paste the material elsewhere. (Cut replaces anything previously copied or cut to

the Clipboard.)

Copy

Places on the clipboard a copy of the current selection in the active window. You can

then paste the material elsewhere. (Copy replaces anything previously copied or cut to

the Clipboard.)

Paste

Pastes the contents of the Clipboard at the current insertion point.

If youre pasting into a layout window, Paste places the contents of the Clipboard inside

the selected view.

Clear

Deletes the current selection without placing the material on the Clipboard.

Duplicate

Makes a copy of the current selection and places the copy slightly offset from the original

in the same parent view.

The Duplicate command is available only when youve selected an item or items in a

layout view.


51/64

CHAPTER 4

NTK Commands

Edit Menu 4-5


Select All

Selects everything in the active window (that is, all views in a layout window, all text in

an editor, or all files in a project window).

Select Hierarchy

Selects all child views of the selected view in a layout window. Selection continues down

the hierarchy to the last child view.

Select in Layout

Selects the view in a layout window that corresponds to the currently selected view

template in a browser. To use the Select in Layout command, first select a template in a

browser, and then choose Select in Layout from the Edit menu.

Shortcut: Double-click on a view template name in a browser window to select thecorresponding view in its layout window.

Use Select in Layout to select invisible or hidden views.

List

Finds and lists instances of a string in the open layout file. The List command displays a

dialog box, illustrated in Figure 3-1, in which you specify the string you want to find and

select search specifications.

Figure 3-1 The dialog for searching with List

When you click Find, NTK finds and lists all matching occurrences of the string.


52/64

CHAPTER 4

NTK Commands

4-6 Edit Menu


Find

Finds a character string in the active text window.

The Find command displays a dialog box, illustrated in Figure 3-2, in which you specify

the text youre interested in and a pair of search specifications.

Figure 3-2 The dialog for searching with Find

When you click Find, NTK finds and selects the next occurrence of the specified string.

The Find command is available only when a text window is active.

Find Next

Finds the next instance of the character string and search criteria specified in the last use

of the Find command.

Find Inherited

Finds the first occurrence of the currently selected slot in the parent view template

hierarchy. The Find Inherited command is available only when a browser window is

active.

The Find Inherited command looks first in the parent of the selected template. If it

doesnt find the selected slot there, it continues up the parent hierarchy to the top level.

When it finds a slot with the same name as the selected slot, NTK opens another browser

window, with the slot and its template selected. If it doenst find the slot in any template

in the hierarchy, NTK sounds the system beep.

Show Clipboard

Opens the Clipboard window.


53/64

CHAPTER 4

NTK Commands

Edit Menu 4-7


Toolkit Preferences

Displays the Toolkit Preferences dialog box, through which you set characteristics of the

Toolkit..

When you click OK, NTK stores your current setting in a preferences file in the system

Preferences folder.

Layout SettingsGrid On Turns autogrid on in all new layout windowsthat is, limits the

placement and sizing of views so that they align with a layout grid.You can control the display of the grid, and you can turn the grid onor off for an individual window, through the Layout menu.

Arrow Keys Move By

With Shift Key Sets the number of pixels by which the selected view is moved orresized when you press an arrow key (or an arrow key and a Shiftkey).

Size Sets the default screen size for layout windows. The default screensize, the size of the Newton MessagePad, is 240 by 336 pixels.


54/64

CHAPTER 4

NTK Commands

4-8 Edit Menu


Browser Settings

View List

Sort By Sets the sort order for names in the template list. The Hierarchyoption sorts templates by their position in the parent/childhierarchy. Type sorts alphabetically by proto template name.

Text Style Sets the text style in which the template names are displayed.

Slots List

Sort By Sets the sort order for names in the slot list.The Name option sortsalphabetically by name; Type sorts alphabetically by data type).

Text Style Sets the text style in which the slot names are displayed.

Show Slot Value Shows the slot value in parentheses next to each slot name.

Auto Apply Applies changes made in an editor automatically when you click on

another slot name or template name, when you close a layout file,or when you build. If this box ix not checked, NTK does not applychanges unless you click the Apply button in the bottom-left cornerof the window.

Text Views

Auto Indent Indents text you enter in a slot text editor .

Tabs Sets the number of spaces in a tab.

Text Style Sets the text style.

Packages

Auto save before building packageAutomatically saves the files associated with all open windowsbefore building a package.

Auto download after building packageAutomatically downloads the package after a build.

Connection

Type Sets the communications protocol for the connection with theNewton PDA.

Port Sets the communications port for the connection with the NewtonPDA.


55/64

CHAPTER 4

NTK Commands

Project Menu 4-9


Project Menu

You use the project menu to manage your application project.

New Project

Creates and opens a new project file and opens a project window.

The project file is the list of files that make up the application, that is, the files that NTK

processes during the build. You add files to the project file through the Add Window and

Add File commands.

You can have only one project open at a time.

Open Project

Opens an existing project file.

Add Window

Adds the file associated with the active layout window to the project.

Add File

Adds a file to the project from anywhere on the desktop, through the standard file-open

dialog box.

Remove File(s)

Removes the selected file or files from a project.

Update File(s)

Build PackageBuilds a package, including the files listed in the project file and following the

specifications in Settings and Toolkit Preferences.

NTK places the package file in the same folder as the project file.The name of the

package file is the name of the project with the suffix .pkg.


56/64


57/64

CHAPTER 4

NTK Commands

Project Menu 4-11


Figure 3-3 The Project Settings dialog box

Application Settings

Name Specifies the text that appears beneath the applications icon in theNewton Extras drawer.

Debug Build Adds a debug slot to each view that you name through Template

Info in the Special menu. The value of thedebug

slot is the viewsname. If youve already created a debug slot for a view, NTK doesnot override that definition.

Debug Build also sets the debugon constant to TRUE.

Symbol Specifies the applications unique symbol. NTK places this symbolin the package during the build.

Note:

Specifying the symbol in the Project Settings window determines thesymbol that NTK places in the package during the build. This symbolsallows the Newton operating system to display and run yourapplication. Newton systems services like Find and Intelligent Assist

also use your applications symbol. To register your application symbolfor system services, you must define an evaluate slot named AppSymbolin the application base view template and set its value to this sameunique symbol name.

To ensure uniqueness across all third-party products, PIE DTSmaintains a registry of developer signatures. Apple recommendsthat you register your companys signature, and then build yourapplication symbols and package names by starting with your own


58/64

CHAPTER 4

NTK Commands

4-12 Project Menu


unique application identifier, followed by a colon, followed by thesignature. A developer with the signature SURF, for example, mightidentify a checkbook application with the symbolcheck:SURF.

To register your signature, contact the registry at

PIESYSOP on AppleLinkorPIESYSOP, MS/305-2A20525 Mariani AveCupertino, CA 95014

Please send this information:

Company nameContact personMailing addressPhone numberEmail addressFirst choice of signature

Second choice of signatureNote that your company name and signature will be publiclyavailable unless you make special arrangements with DTS.

Auto Close

File Selects from the project file a resource file containing theapplications icon resource.

Icon Selects a resource from the file specified in the File pop-up menu.The icon appears to the right of the File and Icon pop-up menus.

NTK recognizes PICT resources. It looks for a mask with a resourcename made from the icon resource name followed by anexclamation point. If an icon is named foo, for example, NTKlooks for a resource with the name foo!.

The icon appears to the right.

NTK looks for the icon mask in a file .

Package Settings

Platform Specifies the model of PDA the application is targeted for.

Delete old package on downloadAutomatically removes a package with the same name beforedownloading a package.

Name Specifies a package name, which must be unique to the application.For a description of package-naming conventions, see the

description of the symbol name beginning on page 4-11.


59/64

CHAPTER 4

NTK Commands

Layout Menu 4-13


Optimize Setting

The Optimize setting determines whether the package is saved in compressed or

uncompressed format. A compressed file takes up less space on the Newton PDA. An

uncompressed file runs faster and uses less battery power.

Space Stores the package in a compressed format.

Speed Stores the package in uncompressed format.

Version

The version number.

This number must be an integer.

Copy Protected

Layout Menu

You use the layout menu to

Layout Size

Displays a dialog box that lets you set the size of the layout in pixels. The default size is

the size of the Newton MessagePad: 240 x 336 pixels.

You can use Layout Size to set up a screen for laying out a print-format file.

Autogrid On

Turns Autogrid on and off. Autogrid restricts the corners of views to nodes on the grid.

The default grid size is 8 by 8 pixels.

Set Grid

Opens a dialog box that lets you change the Autogrid size.

Move to Front

Moves the selected view in front of any sibling views it overlaps by placing it behind its

siblings in the drawing list.


60/64

CHAPTER 4

NTK Commands

4-14 Special Menu


Move to Back

Moves the selected view behind any sibling views it overlaps by placing it ahead of its

siblings in the drawing list.

Move Forward

Moves the selected view one step behind its siblings in the drawing list, so that its

drawn after the view it previously preceded.

The keyboard equivalent for Move Forward is Option-Down Arrow.

Move Backward

Moves the selected view one step ahead of its siblings in the drawing list, so that its

drawn before the view it previously followed.

The keyboard equivalent for Move Backward is Option-Up Arrow.

Alignment

Opens an dialog box that lets you you establish a view alignment scheme thats applied

to the selected views when you choose Align.

A subset of the alignment options appears on the drawing palette.

Align

Aligns the selected views using the alignment scheme through Alignment.

You can apply the simplest alignment schemes by clicking one of the alignment buttons

on the drawing palette.

Preview

Toggles the layout screen between layout mose and preview mode. In Layout mode,

NTK shows the rectangular extents of each view on the screen. In preview mode, NTK

displays the views approximately as they would appear on the Newton screen.

Special Menu

Template Info

Opens a dialog box in which you can name and declare a selected view. A view name

operates as a symbol in NewtonScript. It must be unique. Declaring a view allows you to


61/64

CHAPTER 4

NTK Commands

Special Menu 4-15


access it symbolically from the view in which its declared and from descendants of that

view.

Figure 3-2 illustrates the Template Info dialog box.

Figure 3-4 The Template Info dialog box, for naming and declaring views

NTK does not require you to name all views. When you name a view, NTK appends the

unique view name to the name of the proto template in the template browser list. You

must name

n views that declare themselves to other views

n views to which other views declare themselves.

When you check Allow Access From, NTK activates a pop-up menu containing the

ancestors of the selected view.

New Slot

Opens a window from which you can add a new slot to the currently selected view

template.

When you add a slot to a template, its name appears in the slot list.

To create a new user slot, type in the name of the new slot, then select the kind of editor

this new slot requires. The choice of an editor depends on the type of data the slot will

hold (as shown in Figure 3-4.) Press Add.


62/64

CHAPTER 4

NTK Commands

4-16 Special Menu


Figure 3-5 New Slot Window

Delete Slot

Deletes the selected slot from the view template.

Rename Slot

Opens a window that lets you rename the selected slot. Note that changing the name of

the slot does not change existing occurrences of the name in scripts.

Templates By Type

Lists templates alphabetically by type.

Templates By Hierarchy

Lists templates by hierarchy, with sibling views listed in the order theyre created.


63/64

CHAPTER 4

NTK Commands

Window Menu 4-17


Slots By Name

Lists slots in alphabetical order by name.

Slots By TypeLists slots in alphabetical order by type.

Show Slot Values

Displays the value of each slot in parentheses in the slot list.

Apply

Applies changes made to a slot in an editor.

Revert

Returns slot settings to the values they held after the last Apply.

Window Menu

You use the Window menu to open browser windows and to open the inspector window

or connect the inspector.You use a browser window to create and edit view templates.

The inspector is an interactive debugger.

Open Inspector

Opens the inspector without making a connection to a Newton PDA. Because there is

only one inspector, you can have only one inspector window open at a time.

Connect Inspector

Connects the inspector to a Newton PDA with the Toolkit App installed and aconnection to the development system. If the inspector window is not open, Connect

Inspector opens it.

Chapter 1, Installation and Setup, describes how to set up a connection between the

development system and the PDA and how to install the Toolkit App.

7/27/2019 A Guide to

Date post:	02-Apr-2018
Category:	Documents
Upload:	pablomarx
View:	229 times
Download:	0 times

A Guide to the Newton ToolKit (Alpha Draft 1.1)

Documents