Sei sulla pagina 1di 64

A Guide to the Newton ToolKit

An Introduction to the Newton Toolkit Development Environment

Alpha Draft 1.1 PIE Technical Publications


July 17, 1993 Apple Computer, Inc. 1993

Contents

Preface

A Guide to the Newton Toolkit


How to Use This Book Conventions viii viii

viii

Chapter 1

Installation & Setup

1-1

System Requirements 1-1 Installing NTK Software 1-1 Communicating 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-5 Customizing 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 Dening 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-17 Using the Inspector 2-18

Chapter 3

The Newton ToolKit in Context


Development Cycle Overview 3-1

3-1

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

Project Management Tools 3-2 View Layout Tools 3-4 Drawing, Resizing, and Moving Views 3-6 Drawing a View 3-6 Resizing a View 3-7 Moving and Aligning Views 3-7 Previewing 3-7 Declaring Views 3-8 Linking Multiple Layouts 3-8 Creating Your Own Proto Templates 3-9 Template Browser Tools 3-9 Multiple Browsers 3-10 Project Building Tools 3-10 Debugging Tools 3-11

Chapter 4

NTK Commands

4-1

File Menu 4-1 New Layout 4-1 New Proto Template 4-1 New Print Format 4-1 Open 4-1 Link Layout 4-2 Link Format 4-2 Close 4-2 Save 4-2 Save As 4-2 Save a Copy In 4-3 Save All 4-3 Revert 4-3 Page Setup 4-3 Print One 4-3 Print 4-3 Edit Menu 4-4 Undo 4-4 Cut 4-4 Copy 4-4 Paste 4-4 Clear 4-4 Duplicate 4-4 Select All 4-5 Select Hierarchy 4-5 Select in Layout 4-5 List... 4-5 Find 4-5 Find Next 4-6

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

Find Inherited 4-6 Show Clipboard 4-6 Toolkit Preferences 4-7 Layout Settings 4-7 Browser Settings 4-8 Text 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-10 Package 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-13 Move to Front, Back, Forward or Backward 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

4-13

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

New Browser

4-18

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

Figures and Tables

Chapter 1

Installation & Setup


Table 1-1

1-1 1-1

Hardware and Software Requirements

Chapter 2

A Quick Tour of NTK


Figure 1-1

2-1 2-7

A browser window.

Chapter 3

The Newton ToolKit in Context


Figure 2-1 Figure 2-2 Figure 2-3 Figure 2-4 Figure 2-5 Figure 2-6 Figure 2-7

3-1

Project Window, With Main Layout Window Selected. 3-2 The Project Settings dialog box 3-3 The Toolkit Preferences dialog box 3-4 Layout window and palette 3-5 A layout window with a layout view in place 3-7 Layout Window, in Layout Mode (Left) and Preview Mode 3-8 A Template Browser. Showing a Pending Change in a Slot Editor 3-9

Chapter 4

NTK Commands
Figure 3-1 Figure 3-2 Figure 3-3 Figure 3-4 Figure 3-5

4-1

Project Settings Window 4-11 Moving Views Forward or Backward; Changing the Drawing Order 4-14 Template Info Window for Naming Views 4-15 New Slot Window 4-16 Editing the AppSymbol Slot 4-16

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

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

P R E FA C E

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 all chapters are complete, and those that are may not be current. Please see the release notes for the version of NTK you are using for the most recent 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 Programming Language and the Newton Programmers Guide.
n

Follow the instructions in Chapter 1, Installation and Setup, to install the Newton Toolkit on your development systemand to connect a Newton PDA on which you can test your application. Go through the tutorial in Chapter 2, A Quick Tour of NTK, to familiarize yourself with the basic approach to application development in NTK. Read the description in Chapter 3, The Newton Toolkit in Context, to supplement your understanding of NTK. You might want to read Chapter 3 in conjunction with the tutorial. Use Chapter 4, NTK Commands, as a reference, to look up information as you need it.

Conventions
This book uses the following syntax conventions:

ix
Draft. Preliminary, Condential. 1993 Apple Computer, Inc. 10/6/93

P R E FA C E

Courier

The Courier font represents material that is typed exactly as shown. Keywords, operators, and other reserved elements appear in Courier. All code samples are printed in Courier. Text in italics represents elements that can be replaced by anything that matches their denition. An ellipsis in a syntax description means that the preceding element can be repeated one or more times. An ellipsis in an example represents code not shown.

italics

Changes Since Last Draft


This draft is a signicant editorial departure from previous versions of the Guide 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.

x
Draft. Preliminary, Condential. 1993 Apple Computer, Inc. 10/6/93

CHAPTER

Installation and Setup

This chapter describes


n n

how to install the Newton Toolkit (NTK) on a Macintosh computer how to establish communication between the development system and a Newton PDA 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

Recommended

Minimum

Macintosh Available RAM Operating System System Settings


Note:

Quadra 8 megabytes System 7.1.x or higher 32-bit mode

68030-based Macintosh 8 megabytes System 7.0 with system Tune-up 32-bit mode

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

Installing NTK Software


To install NTK software from disks:

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

1-1

CHAPTER

Installation and Setup

1. Create a New folder on the volume where you want NTK to reside and name the new folder. (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 le, the Teach Text application needed to read the Release Notes, a compressed package le (Newton Toolkit Programs.PKG) and the Applelink Compression Utility. 4. Double-click on the Release Notes le to see if there are any last minute instructions. 5. Double-click on the Newton Toolkit Programs package le you have just moved to the new NTK folder on your hard disk. The Applelink Compression Utility will be launched and will list the contents of the package le. The package le contains the following les: n Apple Modem Tool n AppleTalk ADSP Tool n GlobalData le n MessagePad le n Newton Toolkit, the application le n A suitcase le containing Newton Toolkit fonts n NTK Denition le. 6. Using the Compression Utilities dialog box, choose the new NTK folder you created in step one as the destination for the decompressed les and click OK. The les are decompressed and copied to your new NTK folder. 7. Open the new NTK folder and drag the Apple Modem Tool, the AppleTalk ADSP Tool, and Newton Toolkit font les to your System Folder on the hard disk. Leave the System Folder closed when copying the extensions and respond OK to let the system place the extension and font les 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 directory level as the NTK application. Drag the MessagePad le into this folder. 9. The GlobalData le is initially empty. You can add data to it (refer to GlobalData on page 3-14 for a discussion.) If you use the GlobalData le, it must be in the same folder as the NTK application. 10. The NTK Defnition le contains a list of all the compile-time constants and functions that have been precompiled into NTK. It is for information only and can be put anywhere. 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 le.

1-2

Installing NTK Software


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

CHAPTER

Installation and Setup

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 application package 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 same serial 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-le 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

Communicating With a Newton From NTK


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

1-3

CHAPTER

Installation and Setup

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 a response. In a few seconds, the dialog disappears, and the Toolkit icon appears in the Extras 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 Newton and opens the inspector window if it isnt already open. The Open Inspector item opens and closes the inspector window itself. Opening the inspector window doesnt open a connection, but closing the inspector window closes the connection. When the inspector is connected, its window opens on the Macintosh screen. 4. Type 2 + 1; and press Enter. The inspector displays a reference and the value of the statement, 3.

Troubleshooting
If you encounter difculties 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. If you are using a Powerbook or Powerbook Duo, check that the modem is set to External Modem. If you are using a Powerbook Duo, ensure that theNTK Settings command has selected the Printer-Modem option. Read the Release Notes.

1-4

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

CHAPTER

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 n n n n n

Starting up NTK Setting up an application project Laying out the applications visual interface Dening the behavior of the various elements and establishing access among views Building an application package and downloading it to a PDA Inspecting the application during runtime

Note

This tutorial assumes that youre running NTK on a Macintosh computer with an open connection to a Newton PDA, as described in Chapter 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 le-open dialog box. 2. For this tutorial, click Cancel.

Starting Up NTK
Alpha Draft 1.1. Preliminary, 1993 Apple Computer, Inc. 10/11/93

2-1

CHAPTER

A Quick Tour of NTK

Setting Up a New Project


You build a Newton application from a collection of les, which you administer through a project le. The rst step in creating an application is to start a project le. 1. Choose New Project from the Project menu. NTK presents the standard le-save dialog box. 2. Create a new folder named hello folder, and change the default project name to hello project. 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 your application package. For a description of the Project Settings dialog box, see the description of the Settings command in Chapter 4, Command Reference. 5. Change the application name from ChangeMe to Hello.

2-2

Setting Up a New Project


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

CHAPTER

A Quick Tour of NTK

When you install the nished application on a PDA, this name appears beneath the applications 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 application components.

The default layout window represents the screen of the Newton MessagePad. The NTK graphical editor follows the basic Macintosh interface conventions. For more information, see the section on layout tools in Chapter 3, NTK in Context. 2. Move the pointer over the buttons on the palette.

Starting a Base View and Adding It to the Project


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

2-3

CHAPTER

A Quick Tour of NTK

Note that the item visible in the Selection menu changes as you move the pointer over the buttons. The name of each element appears when the pointer is over the elements button. 3. Press and hold the mouse with the pointer on the Selection pop-up menu. NTK displays the names of all the system-dened components on the palette. You can select elements either by clicking their buttons or by choosing them in the Selection pop-up menu. 4. Using either the buttons or the Selection pop-up menu, select the protoApp template, shown here.

The protoApp template denes a view that can contain other views and that includes a few basic application features: a title bar, a status bar, and a close box. Most applications use either the protoApp template or the clView view class for the base view. (For a description of the system-dened view classes and protos, see the chapter 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 template from which it was constructed. 6. Choose Template Info from the Special Menu.

2-4

Starting a Base View and Adding It to the Project


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

CHAPTER

A Quick Tour of NTK

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

You must supply a unique name for the application base view and for all views that are accessed from other views. 7. Type in the name baseView, and then click OK. 8. To save the layout le that holds the base view, choose Save As from the File menu, type the name main Hello, and then click Save. 9. Choose Add Window from the Project Menu. NTK adds main Hello to the project le. 10. Click the title bar of the project window to see the list of les in the project, which at this point includes only the le main Hello.

By default, NTK designates the rst layout le you add to a project the main layout le, that is, the le containing the base view. Once youve added more views to the project le, you can change the main layout le 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-dened componentstemplates, view classes, and the special linked subview elementfrom the NTK palette. You can also dene your own templates and add them to the palette, as described in Dening Your Own Proto Template beginning on page 2-15. 1. Activate the view window, now titled main Hello, by clicking its title bar. 2. Using either the buttons or the Selection pop-up menu, select protoLabelInputLine from the palette.

Laying Out a View


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

2-5

CHAPTER

A Quick Tour of NTK

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 the Layout 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 dene the structure and behavior of the view. All of the view templates for a single layout window are stored in a single layout le. 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 but outside the text-input view.

2-6

Customizing a View
Alpha Draft 1.1. Preliminary,. 1993 Apple Computer, Inc. 10/11/93

CHAPTER

A Quick Tour of NTK

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.

template list

slot list

slot editor area

The template list shows the base view itself and any views laid out within the base view. The slot list shows the slots that have been dened for the view thats selected in the template list. By default, the rst item in each list is selected when the window rst 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 contents of 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 browser window.
Cancel Apply

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

Customizing a View
Alpha Draft 1.1. Preliminary,. 1993 Apple Computer, Inc. 10/11/93

2-7

CHAPTER

A Quick Tour of NTK

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

6. Save the layout le by choosing Save from the File menu. Note that you cannot save the contents of a browser window. Saving from the browser saves the layout le for the view youre editing.

Adding a Slot
The slot list in the browser window shows the slots that youve dened for a view. You can add system-dened slots to a view through the pop-up menus labeled Specic, Methods, and Attributes (below the slot list).
n

The Specic list contains the optional slots in the proto template on which the current view template is based. Slots in the Specic list may contain either attributes or methods. The Method list contains method slots common to a subset of the proto templates. The Attributes list contains attribute slots common to a subset of the proto templates.

n n

You can also dene 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-dened 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 dened for that view. 3. Choose Label from the Specic pop-up menu. NTK invokes the text editor and displays the default label, Label. It adds the label slot to the slot list.

2-8

Customizing a View
Alpha Draft 1.1. Preliminary,. 1993 Apple Computer, Inc. 10/11/93

CHAPTER

A Quick Tour of NTK

4. Replace the default label with the text My Message 5. Apply the change by clicking the Apply checkmark or by choosing Apply from the Special menu. Again, if the layout window is in preview mode, you can see the change immediately.

6. Save the layout le 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 out separately 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-dened 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 View


In 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 floater message 1.

Adding a Linked View


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

2-9

CHAPTER

A Quick Tour of NTK

3. Choose Add Window from the Project menu to add floater message 1 to the project list. Note that Add Window adds the active view to the project list; Add File displays the le-select dialog box and allows you to add a le 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 rst creating the topmost view and then laying out the view elements within it. For this tutorial, youll use the protoFloatNGo proto, which denes a oating view with a close box. 5. Draw the view, positioning it approximately as shown here.

The rectangle you specify in this step denes the size and location of the linked view. 6. Choose Template Info from the Special menu, name the view MyFloatNGo, and click OK. 7. Select protoStaticText from the palette.

2-10

Adding a Linked View


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

CHAPTER

A Quick Tour of NTK

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

This rectangle denes the location of the static text message within the linked view. 9. Using the Template Info dialog box, name the view myFloater1Message 10. With the myFloater1Message view still selected, choose New Browser from the Window 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 the browser window. (If the view had any descendants, those descendants would also appear in the list.) 11. Double-click on the slotname text 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 le.

Adding a Linked View


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

2-11

CHAPTER

A Quick Tour of NTK

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 the Link 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 specic placement of the linked subview doesnt matter. When the PDA builds the linked view, it uses the specication from the linked views template (in this 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. If floaterLink had more ancestors, they would appear in the popup list. In this example, only baseView is available.

2-12

Adding a Linked View


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

CHAPTER

A Quick Tour of NTK

Allowing access to a view is also known as declaring the view. This example declares the floaterLink view to the baseView view. 7. Click OK. 8. With the floaterLink view still selected, choose Link Layout from the File menu. NTK displays the le-select dialog box. 9. Select the lename floater message 1, and then click Open. The main Hello layout window now reects that floaterLink is linked to the linked view floater message 1.

Adding a Button That Displays the View


To incorporate the oater 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, choose protoTextButton 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 the button 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 then double-click the ButtonClickScript slot to open it for editing. NTK invokes the text editor and displays a skeletal function statement.

Adding a Linked View


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

2-13

CHAPTER

A Quick Tour of NTK

6. Insert an instruction to send an open message to the floaterlink view, so that the text reads: func() begin floaterlink:open() end 7. Apply the change. 8. Double-click the slotname text to open the slot for editing. This slot species the text on the button itself. 9. Change the default button text to Show Linked View. 10. Apply the change. 11. Save the le.

Dening 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 dened 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 le. Dening a layout as a proto, however, opens up two opportunities:
n n

You can use the same template in different views or applications. Your application can use the proto to create views dynamically as needed.

<Note

Creating views dynamically is tricky. Explain why elsewhere, and cross-reference here.>

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 le: you establish 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.

2-14

Dening Your Own Proto Template


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

CHAPTER

A Quick Tour of NTK

3. Draw the layout view approximately as shown here.

4. Select protoRadioButton from the palette.

This proto denes a single, labeled radio button. 5. Draw a wide, at rectangle within the cluster view. <illustratesee step 6 for now> 6. Make two duplicates of the radio button (with the new radio button selected, choose Duplicate twice from the Edit menu), and then position the buttons approximately as shown here.

7. Use the Template Info command to name the layout view myRadioButtons. 8. Save the layout le as myRadioButtonsProto.

Dening Your Own Proto Template


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

2-15

CHAPTER

A Quick Tour of NTK

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 le myRadioButtonsProto to the project. NTK also adds myRadioButtonsProto to the User pop-up menu and makes that menu 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 le.

Building and Downloading a Package


At almost any point in the development process, you can build your application les into a package, which you can download and run on a Newton PDA.

2-16

Building and Downloading a Package


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

CHAPTER

A Quick Tour of NTK

Note

To download, you must have established communication between the development system and the PDA and installed the Toolkit App on the PDA. 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 le called projectname.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 nished (the Hello icon appears in the Extras drawer), open the application 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 between the development system and the PDA and installed the Toolkit App on the PDA. These steps are described in Chapter 1, Installation and Setup.

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.

Using the Inspector


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

2-17

CHAPTER

A Quick Tour of NTK

The inspector window opens on the Macintosh.

Executing Commands
The inspector processes your keystrokes only when you explicitly request it by selecting and 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 of x, 0.333333. You can enter and execute any valid NewtonScript code. The inspector prints to the screen 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 oating 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: <2>, viewclipper: 17861715, base: <1>, viewFlags: 5}, _proto: {viewBounds: {#600047BD}, stepChildren: [#600047FD], _proto: {#2D3}, debug: "floaterLink", preallocatedContext: floaterlink},

2-18

Using the Inspector


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

CHAPTER

A Quick Tour of NTK

viewCObject: 0x1108E20, base: <1>, viewFlags: 65} 5. Close the oater window on the PDA. 6. Put the insertion point anywhere in the line debug("floaterLink") and then press Enter. The inspector responds NIL, because there is no view. <- Embed debugging code in app - Test out a change in the inspector>

Using the Inspector


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

2-19

CHAPTER

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 n n n

managing a project laying out and programming an application building and downloading an executable package debugging

Development Cycle Overview


The Newton PDA environment is a graphical one, in which the user works with visual elements 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 dene 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.

Development Cycle Overview


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

3-1

CHAPTER

Using the Newton Toolkit

Project Management
A NewtonScript application is built from a collection of les:
n n

layout les, which contain the frames you dene in NTKs graphical editor the project data le, which contains your applications installation and shutdown scripts and any expressions youve dened for the build resource les, which contain resources (pictures, sounds, and fonts)

You organize and manage the various component les through a project le, which contains a list of the les in a project. When you open the project le, NTK displays the project window, which lists the les 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 le selected

You create a project le through the New Project item in the Project menu. You add les to the project through the Add Window and Add File commands. You must also specify a collection of project specications through the Settings command. Figure 2-2 illustrates the Project Settings dialog box.

3-2

Project Management
Alpha Draft 1.1. Preliminary,. 1993 Apple Computer, Inc. 10/11/93

CHAPTER

Using the Newton Toolkit

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 identies 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 places in the package during the build. It allows the PDA to recognize and run your application. To register your symbol for system services like Find and Intelligent Assist, you must dene a slot named appSymbol in the application base view template and set its value to this same unique symbol name. For an explanation of registering for system services, see Miscellaneous 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 identiers, 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 elds in Project Settings, see the description of the Settings command in Chapter 4, NTK Commands.

Project Management
Alpha Draft 1.1. Preliminary,. 1993 Apple Computer, Inc. 10/11/93

3-3

CHAPTER

Using the Newton Toolkit

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 Edit menu. Figure 2-3 illustrates the Toolkit Preferences dialog box. For a detailed description of the elds, 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.

3-4

Laying Out Views


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

CHAPTER

Using the Newton Toolkit

Figure 2-4

Layout window and palette

Selection pop-up menu User-dened proto pop-up menu view alignment

linked subview

primitive view classes

The editor saves the views you lay out in a layout le, which contains a hierarchy of views. Each layout le must have a single topmost view, which contains all other views in the layout. The topmost view can contain any number of child views, which themselves 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 for static text or for text in an edit view. prototype templates, constructed from the view classes The prototype templates, or protos, are built into the Newton ROM and provide ready-to-use elements like radio buttons and slide controls. user protos, that is, prototype templates you dene yourself User protos can be based on view classes, system protos, or other user protos. linked subviews, an NTK device for linking in views laid out in separate layout les.

For descriptions of view classes and prototype templates, see the chapters View Basics and Working With Proto Templates in the Newton Programmers Guide.

Laying Out Views


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

3-5

CHAPTER

Using the Newton Toolkit

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 les 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. The view 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 rst 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-dened 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 dened on the screen marks the location of the view. <The actual sizing and displaying of views should anticipate other platforms. You might want to base the applications base view on the results of the GetAppParams function (described in the Newton Programmers Guide), and then justify child views relative to their parent.> Figure 2-5 illustrates a layout window just after its topmost view has been drawn.

3-6

Laying Out Views


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

CHAPTER

Using the Newton Toolkit

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. <resize pointer, Shift-drag, arrow keys, Shift-arrow, groups of views>

Moving and Aligning Views


<drag selection, alignment buttons on palette>

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

Laying Out Views


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

3-7

CHAPTER

Using the Newton Toolkit

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 preview mode

layout mode

Declaring Views
You declare views through the Template Info command in the Special menu. <- summary from Newton Programmers Guide, View Instantiation in Chapter 2, View Basics>

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 le.

3-8

Laying Out Views


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

CHAPTER

Using the Newton Toolkit

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 le 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 specication 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

The Browser
Alpha Draft 1.1. Preliminary,. 1993 Apple Computer, Inc. 10/11/93

3-9

CHAPTER

Using the Newton Toolkit

<callouts: template list (upper left), slot list (upper right), template editing area, cancel button, apply button> 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 dened 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 le. 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 rst 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. <Revise above and add: - Specics, Methods, and Attributes - beforeScripts, afterScripts, viewBounds . . . (See the description of before and after scripts in the next section.)>

Building a Project
You build a project by choosing Build Package from the Project menu. NTK processes the project in this order:
n n n

the print templates the project data le layout les (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 rst and then the view.

3-10

Building a Project
Alpha Draft 1.1. Preliminary,. 1993 Apple Computer, Inc. 10/11/93

CHAPTER

Using the Newton Toolkit

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 n n

any protos referenced in the template the before script if its present the layout, starting at the main layout and then recursively processing all children in order 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 specic to a view. You can use the before script to dene compile-time functions and data, the same way you use the project data le described in the next section. The code in the before and after scripts is not part of the nal 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 variable thisView, 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 := <data to be saved>; 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 a view. 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 names BeforeScript and AfterScript.

Project Data
The project data le is an adjunct to your projectits a way to make declarations available to your project at compile time. Its also the vehicle for dening install and remove scripts.

Building a Project
Alpha Draft 1.1. Preliminary,. 1993 Apple Computer, Inc. 10/11/93

3-11

CHAPTER

Using the Newton Toolkit

You can place in the project data le


n n n

an InstallScript, which is run when your package is installed in the PDA a RemoveScript, which is run when your package is removed other NewtonScript code

This example illustrates a project data le. 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";

3-12

Building a Project
Alpha Draft 1.1. Preliminary,. 1993 Apple Computer, Inc. 10/11/93

CHAPTER

Using the Newton Toolkit

<Explain the constants for the AppSymbol and PackageName. To make your application available for system services, reference AppSymbol through an evaluate slot in your apps base view.> To access a value from the project data le in a run-time script, use it in an evaluate slot.

InstallScript
NTK looks in the project data le 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 named theForm, which contains a reference to your applications base template. You can access information in your application through this slot.

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

RemoveScript
NTK looks in the project data le 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.

Building a Project
Alpha Draft 1.1. Preliminary,. 1993 Apple Computer, Inc. 10/11/93

3-13

CHAPTER

Using the Newton Toolkit

NewtonScript Code
You can dene constants and functions in the project data le with the constant and func statements, described in NewtonScript Programming Language. You can assign a constant to any literal expression but not compound expressions or dynamically created objects.

GlobalData
The GlobalData le is an adjunct to NTK. You can place in it NewtonScript code that you want available from any project. The GlobalData le 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, lename, and line number. When you dismiss the error dialog, NTK quits. The prudent course is to develop code in the project data le and move it to GlobalData only when its debugged.

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. <Minimum description of inspector: Type instructionsdebugging functions or NewtonScript code. To execute the current line, press Enter. To execute a block of text, select and then press Enter. See tutorial in this manual for brief examples. See the chapter Debugging in the Newton Programmers Guide for the debugging functions. >

3-14

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

CHAPTER

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 les.

New Layout
Opens a new layout window and creates an associated layout le.

New Proto Template


Opens a new proto template layout window and creates an associated proto le. You use this command to lay out your own proto templates, which you can add to the layout palette. See <x-ref to tutorial> 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 le. 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 that when the user prints a view from the screen, the application uses the print format instead of the screen format.

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

4-1

CHAPTER

NTK Commands

Open
Opens a saved layout le. The Open command displays the le-open dialog box, which lets you select a le to open <art: Standard File open> You open a project le 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 le-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 le. Close can affect a layout le, a project le, a browser window, or the inspector window. If you close a window thats been edited since its le was last saved, NTK displays a verication dialog box that gives you a chance to save changes before closing the window.

Save
Saves the le associated with the active window. The saved le replaces the previously saved le of the same name. The le remains open. The Save command affects only the one active window, that is,
n n n n

the layout le for the active layout window, the layout le for the active browser window, the project le associated with an active project window, or the contents of the inspector window, if its active.

Save As
Saves a new copy of the le associated with the active window. The Save As command opens a le-save dialog box, through which you specify the new name and location. Save As changes the name of the active window and closes the le associated with the windows previous name. <art: Save As dialog box> You use Save As to name or rename a layout window. Because the Save As command displays the standard le-save dialog box, you can also use it to create a new folder. 4-2

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

CHAPTER

NTK Commands

Save a Copy In
Saves a separate copy of a layout or Inspector le, with the name and location you specify through the le-save dialog box. The Save a Copy In command does not change the name or path of the active window and leaves its associated le open. You use Save a Copy In to back up a le or to make a copy of a layout that you might want to use in another application.

Save All
Saves all open layout les under the names already established. If youve not yet saved a le associated with one of the windows, NTK prompts you for the necessary lenames. Use Save All before each project build to ensure that the project les match all changes youve made.

Revert
Restores the last saved version of the le 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. <art: page setup dialog box>

Print One
Prints one copy of the le associated with the active window on the printer already selected through the Chooser. This command prints without displaying the Print dialog box for your verication.

Print
Prints the le associated with the active window. When you choose Print, NTK displays the printing dialog box, which identies the selected printer and lets you verify or change the printing options. <art: print dialog box>
Note

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

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

4-3

CHAPTER

NTK Commands

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.

4-4

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

CHAPTER

NTK Commands

Select All
Selects everything in the active window (that is, all views in a layout window, all text in an editor, or all les 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, rst 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 the corresponding 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 le. The List command displays a dialog box, illustrated in Figure 3-1, in which you specify the string you want to nd and select search specications.

Figure 3-1

The dialog for searching with List

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

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

4-5

CHAPTER

NTK Commands

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 specications.

Figure 3-2

The dialog for searching with Find

When you click Find, NTK nds and selects the next occurrence of the specied 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 specied in the last use of the Find command.

Find Inherited
Finds the rst 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 rst in the parent of the selected template. If it doesnt nd the selected slot there, it continues up the parent hierarchy to the top level. When it nds 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 nd the slot in any template in the hierarchy, NTK sounds the system beep.

Show Clipboard
Opens the Clipboard window.

4-6

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

CHAPTER

NTK Commands

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 le in the system Preferences folder.

Layout Settings
Grid 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 on or 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 or resized when you press an arrow key (or an arrow key and a Shift key). Size Sets the default screen size for layout windows. The default screen size, the size of the Newton MessagePad, is 240 by 336 pixels.

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

4-7

CHAPTER

NTK Commands

Browser Settings
View List Sort By Sets the sort order for names in the template list. The Hierarchy option sorts templates by their position in the parent/child hierarchy. Type sorts alphabetically by proto template name. Sets the text style in which the template names are displayed.

Text Style Slots List Sort By Text Style Show Slot Value Auto Apply

Sets the sort order for names in the slot list.The Name option sorts alphabetically by name; Type sorts alphabetically by data type). Sets the text style in which the slot names are displayed. Shows the slot value in parentheses next to each slot name. Applies changes made in an editor automatically when you click on another slot name or template name, when you close a layout le, or when you build. If this box ix not checked, NTK does not apply changes unless you click the Apply button in the bottom-left corner of the window.

Text Views
Auto Indent Tabs Text Style Indents text you enter in a slot text editor <to the indent of the previous line>. Sets the number of spaces in a tab. Sets the text style.

Packages
Auto save before building package Automatically saves the les associated with all open windows before building a package. Auto download after building package Automatically downloads the package after a build.

Connection
Type Port Sets the communications protocol for the connection with the Newton PDA. Sets the communications port for the connection with the Newton PDA.

4-8

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

CHAPTER

NTK Commands

Project Menu
You use the project menu to manage your application project.

New Project
Creates and opens a new project le and opens a project window. The project le is the list of les that make up the application, that is, the les that NTK processes during the build. You add les to the project le through the Add Window and Add File commands. You can have only one project open at a time.

Open Project
Opens an existing project le.

Add Window
Adds the le associated with the active layout window to the project.

Add File
Adds a le to the project from anywhere on the desktop, through the standard le-open dialog box.

Remove File(s)
Removes the selected le or les from a project.

Update File(s)
<To be provided.>

Build Package
Builds a package, including the les listed in the project le and following the specications in Settings and Toolkit Preferences. NTK places the package le in the same folder as the project le.The name of the package le is the name of the project with the sufx .pkg.

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

4-9

CHAPTER

NTK Commands

Download Package
Downloads a package to a Newton PDA with the Toolkit App installed and a connection to the computer running NTK.

Export Package to Text


Writes the contents of the project data le and all les in a project into a text le. The name of the le is the project name with the sufx .TEXT. You can open this le in any application that recognizes text les. You cannot read the le back into NTK.

Install Toolkit App


Installs the Toolkit App on a Newton PDA connected to the development system. The Toolkit App handles the downloading of packages and supports the inspector. Chapter 1, Installation and Setup, describes how to set up a connection between the development system and the PDA.

Mark As Main Layout


Designates the selected le in the project window as the main layout le, that is, the template le whose topmost view is the application base view.

Project Data
Opens a window for editing the project data le. The project data le is the rst le processed during a build. It contains an applications install and remove scripts as well as declarations and other NewtonScript code referenced throughout the project. For more information, see Building a Project in Chapter 3, Using NTK.

Settings
Lets you set project specications through the dialog box illustrated in Figure 3-1.

4-10

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

CHAPTER

NTK Commands

Figure 3-3

The Project Settings dialog box

Application Settings
Name Debug Build Species the text that appears beneath the applications icon in the Newton Extras drawer. Adds a debug slot to each view that you name through Template Info in the Special menu. The value of the debug slot is the views name. If youve already created a debug slot for a view, NTK does not override that denition. Debug Build also sets the debugon constant to TRUE. <explain> Species the applications unique symbol. NTK places this symbol in the package during the build.

Symbol

Note:

Specifying the symbol in the Project Settings window determines the symbol that NTK places in the package during the build. This symbols allows the Newton operating system to display and run your application. Newton systems services like Find and Intelligent Assist also use your applications symbol. To register your application symbol for system services, you must dene an evaluate slot named AppSymbol in the application base view template and set its value to this same unique symbol name. To ensure uniqueness across all third-party products, PIE DTS maintains a registry of developer signatures. Apple recommends that you register your companys signature, and then build your application symbols and package names by starting with your own

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

4-11

CHAPTER

NTK Commands

Auto Close File Icon

unique application identier, followed by a colon, followed by the signature. A developer with the signature SURF, for example, might identify a checkbook application with the symbol check:SURF. To register your signature, contact the registry at PIESYSOP on AppleLink or PIESYSOP, MS/305-2A 20525 Mariani Ave Cupertino, CA 95014 Please send this information: Company name Contact person Mailing address Phone number Email address First choice of signature Second choice of signature Note that your company name and signature will be publicly available unless you make special arrangements with DTS. <to come> Selects from the project le a resource le containing the applications icon resource. Selects a resource from the le specied 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 resource name made from the icon resource name followed by an exclamation point. If an icon is named foo, for example, NTK looks for a resource with the name foo!. The icon appears to the right. NTK looks for the icon mask in a le .

Package Settings
Platform Species the model of PDA the application is targeted for. Delete old package on download Automatically removes a package with the same name before downloading a package. Name Species 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.

4-12

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

CHAPTER

NTK Commands

Optimize Setting
The Optimize setting determines whether the package is saved in compressed or uncompressed format. A compressed le takes up less space on the Newton PDA. An uncompressed le runs faster and uses less battery power. Space Speed Stores the package in a compressed format. Stores the package in uncompressed format.

Version
The version number. <Give more info.> This number must be an integer.

Copy Protected
<To come>

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 le.

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.

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

4-13

CHAPTER

NTK Commands

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

4-14

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

CHAPTER

NTK Commands

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 n

views that declare themselves to other views 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.

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

4-15

CHAPTER

NTK Commands

Figure 3-5

New Slot Window

<Specic, Methods, and Attributes pop-up menus. Editors.

>

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.

4-16

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

CHAPTER

NTK Commands

Slots By Name
Lists slots in alphabetical order by name.

Slots By Type
Lists 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. <That is, compiles and updates le in memory. Does not save.>

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 a connection 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.

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

4-17

CHAPTER

NTK Commands

New Browser
Opens a new template browser at the level of the selected view in a layout window.

Figure 3-6

A browser window

A browser window lets you examine the template hierarchy and edit slots in templates at and below the selected view. A browser at the base view, for example, gives you access to all templates in the le. You can open multiple browsers.

4-18

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