Newton Toolkit User's Guide

Newton Toolkit Users Guide
Apple Computer, Inc. 1993, 1994, Apple Computer, Inc. All rights reserved. No part of this publication or the software described in it may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means, mechanical, electronic, photocopying, recording, or otherwise, without prior written permission of Apple Computer, Inc., except in the normal use of the software or to make a backup copy of the software. The same proprietary and copyright notices must be afxed to any permitted copies as were afxed to the original. This exception does not allow copies to be made for others, whether or not sold, but all of the material purchased (with all backup copies) may be sold, given, or loaned to another person. Under the law, copying includes translating into another language or format. You may use the software on any computer owned by you, but extra copies cannot be made for this purpose. Printed in the United States of America. The Apple logo is a registered trademark of Apple Computer, Inc. Use of the keyboard Apple logo (Option-Shift-K) for commercial purposes without the prior written consent of Apple may constitute trademark infringement and unfair competition in violation of federal and state laws. No licenses, express or implied, are granted with respect to any of the technology described in this book. Apple retains all intellectual property rights associated with the technology described in this book. This book is intended to assist application developers to develop applications only for licensed Newton platforms.
Apple Computer, Inc. 20525 Mariani Avenue Cupertino, CA 95014 408-996-1010 Apple, the Apple logo, APDA, AppleLink, AppleTalk, LaserWriter, Macintosh, Macintosh Quadra, MPW, Newton, and PowerBook are trademarks of Apple Computer, Inc., registered in the United States and other countries. Finder, the light bulb logo, MessagePad, NewtonScript, Newton Toolkit, PowerBook Duo, ResEdit, and System 7 are trademarks of Apple Computer, Inc. Adobe Illustrator and PostScript are trademarks of Adobe Systems Incorporated, which may be registered in certain jurisdictions. FrameMaker is a registered trademark of Frame Technology Corporation. Helvetica and Palatino are registered trademarks of Linotype Company. ITC Zapf Dingbats is a registered trademark of International Typeface Corporation. Simultaneously published in the United States and Canada.
ALL IMPLIED WARRANTIES ON THIS MANUAL, INCLUDING IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE, ARE LIMITED IN DURATION TO NINETY (90) DAYS FROM THE DATE OF THE ORIGINAL RETAIL PURCHASE OF THIS PRODUCT. Even though Apple has reviewed this manual, APPLE MAKES NO WARRANTY OR REPRESENTATION, EITHER EXPRESS OR IMPLIED, WITH RESPECT TO THIS MANUAL, ITS QUALITY, ACCURACY, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE. AS A RESULT, THIS MANUAL IS SOLD AS IS, AND YOU, THE PURCHASER, ARE ASSUMING THE ENTIRE RISK AS TO ITS QUALITY AND ACCURACY. IN NO EVENT WILL APPLE BE LIABLE FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES RESULTING FROM ANY DEFECT OR INACCURACY IN THIS MANUAL, even if advised of the possibility of such damages. THE WARRANTY AND REMEDIES SET FORTH ABOVE ARE EXCLUSIVE AND IN LIEU OF ALL OTHERS, ORAL OR WRITTEN, EXPRESS OR IMPLIED. No Apple dealer, agent, or employee is authorized to make any modication, extension, or addition to this warranty. Some states do not allow the exclusion or limitation of implied warranties or liability for incidental or consequential damages, so the above limitation or exclusion may not apply to you. This warranty gives you specic legal rights, and you may also have other rights which vary from state to state.
LIMITED WARRANTY ON MEDIA AND REPLACEMENT If you discover physical defects in the manual or in the media on which a software product is distributed, APDA will replace the media or manual at no charge to you provided you return the item to be replaced with proof of purchase to APDA.
Contents
Figures and Tables xi xv
Preface
About This Book
How to Use This Book xv Related Books xvi Conventions xvii Developer Products and Support
xviii
Chapter 1
Installation and Setup
1-1
System Requirements 1-1 Installing NTK on the Macintosh 1-2 Installing the Toolkit App on the Newton Making the Physical Connection 1-5 Downloading the Toolkit App 1-6 Making an Inspector Connection 1-7 Troubleshooting 1-8
1-5
Chapter 2
Programming With theNewton Toolkit

Terms and Concepts 2-1 The NTK Development Process 2-3
2-1
iii
Chapter 3
A Quick Tour of NTK
3-1
Starting Up NTK 3-2 Setting Up a New Project 3-2 Starting a Layout File and Adding It to the Project 3-4 Laying Out Application Elements 3-8 Customizing a View Template 3-9 Editing a Slot 3-10 Adding a Slot 3-11 Building and Downloading a Package 3-12 Adding a Linked Layout 3-14 Laying Out a Linked View 3-15 Linking a Layout 3-17 Adding a Button That Displays the View 3-19 Dening Your Own Proto 3-21 Laying Out a Proto and Adding It to the Palette 3-21 Using Your Proto 3-25 Using the Inspector 3-26 Connecting the Inspector 3-26 Executing Commands 3-27 Looking at a Frame 3-28 Making a Change in a Running Application 3-30
Chapter 4
Using the Newton Toolkit

Setting Up a Project 4-1 Project File 4-2 Project Settings 4-3 Application Settings 4-4 Package Settings 4-6 Setting Preferences 4-7 Layout Settings 4-8 Browser Settings 4-9 View List 4-9 Slot List 4-9
4-1
iv
Text Views 4-10 Packages 4-10 Connection 4-10 Heap Sizes in KBytes 4-11 Laying Out Views 4-11 Drawing, Resizing, and Moving Views 4-13 Drawing a View 4-13 Resizing a View 4-16 Moving a View 4-17 Aligning Views 4-18 Ordering Views 4-19 Previewing 4-20 Naming and Declaring Views 4-21 Linking Multiple Layouts 4-22 Creating User Protos 4-24 Creating Print Format Templates 4-25 Browsing and Editing Templates 4-26 Browsing Templates 4-26 Adding Slots 4-28 Editing Slots 4-30 Editing Text 4-32 Searching for Text in Files 4-34 Listing Instances of a String 4-34 Finding Instances of a String 4-35 Finding Slots in the Hierarchy 4-36 Building a Project 4-37 The Build Environment 4-38 Global Data File 4-38 Project Data File 4-39 Variables and Constants 4-42 Platform Files 4-43 Resources 4-44 Merging Packages 4-45
Build Sequences 4-46 Building an Application Building a Book 4-48 Processing a Layout File Error Messages 4-50 Debugging With the Inspector
4-47 4-49 4-51
Chapter 5
Debugging
5-1
The Inspector 5-1 Using the Inspector 5-2 Tracing the Execution of Your Application 5-3 Examining the Program Stack 5-5 Breaking for Exceptions 5-8 Displaying Information in the Inspector Window 5-9 Printing Objects in the Inspector Window 5-10 Displaying the Contents of a View 5-13 Displaying the View Hierarchy 5-14 Debugging Variables 5-15 Debugging Functions 5-16 Newton Programming Problems and Tips 5-23 Common Programming Problems 5-23 Setting the Wrong Slot Value 5-23 Forgetting to Set the Function Return Value 5-25 Producing Memory Problems With Dangling Frame References 5-26 Generating Unexpected Comparison Results With nil Values 5-26 Using nil in Expressions 5-28 Trying to Resize a Read-Only Object 5-29 Text Is Not Drawing 5-30 Problems with Printing and Communications 5-31
vi
Programming Tips for Debugging 5-31 Using Global Variables to Examine Exceptions Maintaining View State 5-32 Accessing the Parent of a View 5-33 Peeking Into a Soup 5-33
5-32
Chapter 6
NTK Commands
6-1
File Menu 6-1 New Layout (Command-N) 6-1 New Proto Template (Command-T) New Print Format 6-2 Open (Command-O) 6-2 Link Layout 6-2 Close (Command-W) 6-3 Save (Command-S) 6-3 Save As 6-3 Save a Copy In 6-4 Save All (Command-M) 6-4 Revert 6-4 Page Setup 6-4 Print One 6-5 Print (Command-P) 6-5 Quit (Command-Q) 6-5 Edit Menu 6-5 Undo (Command-Z) 6-5 Cut (Command-X) 6-6 Copy (Command-C) 6-6 Paste (Command-V) 6-6 Clear 6-6 Duplicate (Command-D) 6-6 Select All (Command-A) 6-6 Select Hierarchy 6-7 Select in Layout 6-7
6-2
vii
List (Command-L) 6-7 Find (Command-F) 6-8 Find Next (Command-G) 6-8 Find Inherited 6-9 Newt Screen Shot 6-9 Show Clipboard 6-9 Toolkit Preferences 6-9 Project Menu 6-10 New Project 6-11 Open Project 6-11 Add Window 6-11 Add File 6-11 Add Book File 6-11 Remove File 6-11 Update File 6-12 Build Package (Command-1) 6-12 Download Package (Command-2) 6-12 Export Package to Text 6-12 Install Toolkit App 6-13 Mark as Main Layout 6-13 Project Data 6-13 Settings 6-13 Layout Menu 6-14 Layout Size 6-15 Autogrid On 6-15 Set Grid 6-15 Move To Front 6-16 Move To Back 6-16 Move Forward 6-16 Move Backward 6-17 Alignment 6-17 Align 6-18 Preview (Command-Y) 6-18
viii
Browser Menu 6-18 Template Info (Command-I) 6-18 New Slot (Command-=) 6-19 Rename Slot 6-20 Delete Slot 6-20 Templates by Type 6-20 Templates by Hierarchy 6-21 Slots by Name 6-21 Slots by Type 6-21 Show Slot Values 6-21 Apply (Command-E) 6-21 Revert 6-21 Window Menu 6-22 Open Inspector 6-22 Connect Inspector (Command-K) 6-22 New Browser (Command-B) 6-22
Appendix A
Keyboard Text-Editing Commands

Setting the Insertion Point A-1 Selecting Text A-3 Manipulating Selected Text A-4 Deleting Text A-5 Changing the Meaning of the Next Keystroke
A-1
A-6
Appendix B
Keyboard Shortcuts
B-1
ix
Appendix C
Using Resources
C-1
About Resources C-1 Resource Files C-2 Adding Resource Files to a Project C-2 Using Resources C-2 Opening and Closing Resource Files C-3 Extracting Resource Data C-4 Using the Resource-Handling Functions C-6 Using 'PICT' Resources C-7 Making a Bitmap From a 'PICT' Resource C-7 Using External Sound Resources C-8 Resource Functions C-9 Opening and Closing Resource Files C-9 Retrieving Resources C-10 Summary of Resource-Manipulation Functions C-15 Opening and Closing Resource Files C-15 Getting Resource Data C-15
Appendix D
Specialized Slot Editors

Script Slots D-1 View Attributes D-2 viewBounds D-2 viewFlags D-4 viewFormat D-4 viewJustify D-4 viewEffect D-5 viewTransferMode D-5 Specic Slots D-5
D-1
Index
IN-1
Figures and Tables
Chapter 1

Table 1-1
1-1 1-2
Hardware and software requirements
Chapter 2
Programming With theNewton Toolkit

Figure 2-1
2-1 2-4
The Newton application development process
Chapter 3
A Quick Tour of NTK

Figure 3-1 Figure 3-2
3-1 3-5
Layout window and palette A browser window 3-11
Chapter 4

Figure 4-1 Figure 4-2 Figure 4-3 Figure 4-4 Figure 4-5 Figure 4-6 Figure 4-7 Figure 4-8 Figure 4-9 Figure 4-10 Figure 4-11 Figure 4-12
4-1
The project window, with the main layout le selected 4-3 The Project Settings dialog box 4-3 The Toolkit Preferences dialog box 4-8 Layout window and palette 4-12 A layout window with the layout view in place 4-15 The Alignment dialog box 4-18 The layout window in layout and preview modes 4-21 The Template Info dialog box, for naming and declaring views 4-22 Declaring views across linked layout les 4-24 A browser window with the view ags slot open for editing 4-27 The New Slot dialog box 4-29 The Editor pop-up menu in the New Slot dialog box 4-29
xi
Figure 4-13 Figure 4-14 Figure 4-15 Figure 4-16 Figure 4-17 Figure 4-18
Initial contents of evaluate, script, and text slots 4-30 The number, Boolean, rectangle, and picture slot editors 4-31 The Inspector window with a help message displayed 4-33 The dialog box for searching with List 4-34 The dialog for searching with Find 4-36 Inspector window 4-51
Chapter 5
Debugging
Table 5-1 Table 5-2
5-1 Debugging variables 5-15 Exception handling global variables
5-32
Chapter 6
NTK Commands
Figure 6-1 Figure 6-2 Figure 6-3 Figure 6-4 Figure 6-5 Figure 6-6 Figure 6-7 Figure 6-8 Figure 6-9 Figure 6-10
6-1
The dialog for searching with List 6-7 The dialog for searching with Find 6-8 The Toolkit Preferences dialog box 6-10 The Project Settings dialog box 6-14 The Layout Size dialog box 6-15 The Set Grid dialog box 6-16 The Alignment dialog box 6-17 The Template Info dialog box, for naming and declaring views 6-19 The New Slot dialog box 6-19 The Rename Slot dialog box 6-20
Appendix A

Table A-1 Table A-2 Table A-3 Table A-4 Table A-5
A-1
Moving the insertion point A-2 Selecting text with keyboard commands Manipulating selected text A-4 Deleting text with keyboard commands Changing the interpretation of the next keystroke A-6
A-3 A-5
xii
Appendix B
Keyboard Shortcuts
Table B-1 Table B-2
B-1
Keyboard equivalents to menu items B-1 Keyboard commands that affect the hierarchy
B-3
Appendix C
Using Resources
Figure C-1
C-1
Adding a named 'PICT' resource to a picture slot C-7
Appendix D

Table D-1 Table D-2
D-1
Meaning of viewBounds elds for horizontal justication D-3 Meaning of viewBounds elds for vertical justication D-3
xiii
P R E FA C E
About This Book

This book introduces the Newton Toolkit (NTK), an integrated environment for developing Newton applications. You program Newton applications in NewtonScript, an object-oriented language developed for the Newton family of personal digital assistants (PDAs).
How to Use This Book

This book is both a tutorial introduction and a reference guide to NTK. You use this book in conjunction with The NewtonScript Programming Language and the Newton Programmers Guide. This book contains six chapters:
n
Chapter 1, Installation and Setup, contains instructions for installing the Newton Toolkit on your Macintosh computer, attaching a Newton PDA, installing Toolkit software on the Newton, and setting up a debugging connection. Chapter 2, Programming With the Newton Toolkit, introduces Newton programming terminology, describes the Newton development process, and introduces the basic components of the Newton Toolkit. Chapter 3, A Quick Tour of NTK, is a tutorial designed to familiarize you with the basic process of application development in NTK. Chapter 4, Using the Newton Toolkit, describes the components of the Newton Toolkit in detail.
xv
P R E FA C E
Chapter 5, Debugging, explains how to use the debugging commands available through the Inspector and offers a few debugging guidelines. Chapter 6, NTK Commands, is a summary of the items available in the NTK menus.
Related Books
This book is one in a set of books included with the Newton Toolkit development environment. Youll also need the other books in the set:
n
Newton Programmers Guide. This book is the denitive guide and reference for Newton programming. It explains how to write Newton programs and describes the system software routines that you can use to do so. The NewtonScript Programming Language. This book describes the NewtonScript programming language. Newton Book Maker Users Guide. This book describes how to use Newton Book Maker and the Newton Toolkit to make Newton digital books and to add online help to Newton applications. This book is included only if you purchased the Newton Toolkit package that includes Book Maker.
xvi
P R E FA C E
Conventions
This book uses the following font and syntax conventions: Courier The Courier font represents material that is typed exactly as shown. Code listings, code snippets, and special identiers in the text such as predened system frame names, slot names, function names, method names, symbols, and constants are shown in the Courier typeface to distinguish them from regular body text. Text in italics represents replacable elements, such as function parameters, which you must replace with your own values. Key terms and concepts are printed in boldface where theyre dened. Words dened in this book appear in the glossary in the Newton Programmers Guide. An ellipsis in a syntax description means that the preceding element can be repeated one or more times. An ellipsis in a code example represents code not shown. [] Square brackets enclose optional elements in syntax descriptions.
italics
boldface
xvii
P R E FA C E
Developer Products and Support

APDA is Apples worldwide source for a large number of development tools, technical resources, training products, and information for anyone interested in developing applications on Apple platforms. Every four months, customers receive the APDA Tools Catalog featuring current versions of Apples development tools and the most popular third-party development tools. Ordering is easy; there are no membership fees, and application forms are not required for most products. APDA offers convenient payment and shipping options including site licensing. To order product or to request a complimentary copy of the APDA Tools Catalog: APDA Apple Computer, Inc. P.O. Box 319 Buffalo, NY 14207-0319 Telephone 1-800-282-2732 (United States) 1-800-637-0029 (Canada) 716-871-6555 (International) 716-871-6511 APDA APDA 76666,2405 APDA@applelink.apple.com
Fax AppleLink America Online CompuServe Internet
If you provide commercial products and services, call 408-974-4897 for information on the developer support programs available from Apple.
xviii
CHAPTER
The Newton Toolkit (NTK) runs on a Macintosh computer in 32-bit mode with a minimum of 8 megabytes of RAM. NTK includes a small application the Toolkit Appthat runs on a Newton Personal Digital Assistant (PDA). This chapter describes how to
n n n n
install NTK on a Macintosh computer download the Toolkit App to a Newton establish a debugging connection between the Macintosh and the Newton troubleshoot installation and setup
System Requirements
Table 1-1 lists NTKs hardware and software requirements.
Note
Downloading to a Newton also requires one free serial port on the Macintosh. u
System Requirements
1-1
CHAPTER
Table 1-1
Hardware and software requirements
Recommended
Minimum
Macintosh Model Available RAM Operating System System Settings
Quadra 8 megabytes System 7.1.x or higher 32-bit mode
25 Mhz 68030-based Macintosh 8 megabytes System 7.0 with System 7 Tune-Up 32-bit mode
Installing NTK on the Macintosh

The Newton Toolkit is shipped with an installation script, which you run from the distribution disk. Before installing NTK, verify that each distribution disk is locked (that is, that the write-protect slider is open) to protect the contents from accidental overwriting. Follow the steps in this section to install NTK on the Macintosh. 1. Insert the disk Newton Toolkit Installer. The disk opens to show the release notes and the Installer.
2. Double-click the release notes and read them to see if there are any updates to the installation procedure. If not, close them and continue with these directions.
1-2
CHAPTER
3. Double-click the Installer icon to begin installation.
If youre installing NTK for the rst time, of if youre simply updating an earlier release, leave the Easy Install item selected in the pop-up menu in the top-left corner of the window. You can also choose Custom Install to selectively install parts of the software or Custom Remove to selectively remove parts of the software. By default, the Installer puts NTK in a folder named Newton Toolkit on your startup disk. If you want to change the destination, click Select Folder and specify a new or different folder. 4. Click Install. The Installer begins copying and conguring software; it displays progress reports and prompts you to insert disks when necessary. 5. Insert disks as prompted until the Installer reports that installation is complete. 6. Click Quit to quit the Installer.
1-3
CHAPTER
The Newton Toolkit folder contains the NTK application and various support tools:
The EditorCommands le, which is used by NTK and which must remain in the same folder as NTK. The NTK Denitions le, which contains a list of compile-time constants and functions available in NTK. This le is for your information only and can be put anywhere. The Platforms folder, which at this release contains a le named MessagePad. Platform les contain data specic to a Newton platform. The Platforms folder must remain in the same folder as NTK. The Toolkit App package, which contains a companion application that runs on a Newton. Instructions for installing the Toolkit App appear in the next section. The Newton Book Maker application, for generating book les that can be read into NTK. This application is documented in the Newton Book Maker Users Guide. The Newton Package Installer, a stand-alone utility that downloads packages to a Newton. You are free to ship this utility as an installation tool for your customers. The TextText application, for reading the release notes. This le can be stored anywhere.
1-4
CHAPTER
Release notes for the Newton Toolkit, the Platform les, and Newton Book Maker. These les are for you information only and can be put anywhere.
The Installer also installs fonts in the System Folder if necessary and places the Apple Modem Tool and AppleTalk ADSP Tool in the Extensions folder in the System Folder.
Installing the Toolkit App on the Newton

You can install the Toolkit App over either a direct serial connection or an AppleTalk network connection. Once youve installed the Toolkit App, it 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.
Making the Physical Connection

You can connect your development system directly 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. You can use either the modem serial port or the printer serial port; NTK is congured to use the modem port by default.
Note
Make sure that no other piece of Macintosh software is using the same serial port. u If both the Macintosh and the Newton are connected to an AppleTalk network, you can also download over the Toolkit App over the network.
1-5
CHAPTER
Downloading the 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. 1. On the Macintosh, start NTK by double-clicking the application icon. The Macintosh displays the open-le dialog box, for opening an NTK project. 2. Dismiss the dialog box by clicking Cancel. 3. Choose Install Toolkit App from the Project menu. NTK displays the connection settings and prompts you to initiate the connection on the Newton. 4. On the Newton, open the Extras drawer, and then tap the Connection icon. The Connection application opens on the Newton screen.
5. Verify that the connection setting matches your conguration. 6. Tap Connect. The Newton reports that the Connection application is waiting for a response. In a few seconds, the dialog disappears, and a toollbox icon labeled Toolkit appears in the Extras drawer. NTK Toolkit App installation is complete. To install the Toolkit App over an AppleTalk network, you must change NTKs communication settings through the Toolkit Preferences item in the Edit menu. On the Newton, you must select the zone and name of the host Macintosh in the Connection application on the Newton.
1-6
CHAPTER
Making an Inspector Connection

An Inspector connection lets you issue commands directly to the Newton from a window on the Macintosh. You can establish an Inspector connection only over a serial line. To open and test an Inspector connection 1. On the Macintosh, choose Connect Inspector from the Window menu. NTK displays the connection settings and prompts you to initiate the connection on the Newton. 2. On the Newton, open the Toolkit App by tapping its icon in the Extras drawer.
3. Verify that Macintosh serial is selected; if its not, change the selection. 4. Tap Connect Inspector. The Macintosh and the Newton establish communication, and the Macintosh displays the Inspector window. 5. In the Inspector window, type x := 1/5; 6. Press Enter. The Inspector displays a reference and the value of x. #440D2F1 0.200000
Making an Inspector Connection
1-7
CHAPTER
Troubleshooting
If you have trouble launching NTK, try these troubleshooting strategies:
n
Verify that the Macintosh is using 32-bit addressing. You set the addressing mode in the Memory control panel, available through the Control Panel item in the Apple menu. Verify that the folder containing the Newton Toolkit application also contains a Platforms folder that contains the MessagePad le. Read the release notes.
If you have trouble downloading the Toolkit App or making an Inspector connection, try these troubleshooting strategies:
n n
Verify that youre using a null modem cable. If youre using a Powerbook or Powerbook Duo, verify that the modem is set to External Modem. If youre using a Powerbook Duo, turn off AppleTalk through the Chooser. If youre using a Quadra AV, verify that youre not using the World port. Delete the Newton Toolkit Preferences le in the Preferences folder in the System Folder before launching NTK, and then re-establish communications settings through the Toolkit Preferences item in the Edit menu. Reset the Newton. If the Newton has little free space, remove some software through the Memory item in Preferences. Verify that the Apple Modem Tool and the AppleTalk ADSP Tool are installed in the Extensions folder in the System Folder. Read the release notes.
n n n
n n
1-8
Troubleshooting
CHAPTER
Programming With the Newton Toolkit
The Newton interface is a graphical one, in which the user manipulates elements on the screen to accomplish a wide range of tasks. The Newton Toolkit is an integrated environment tailored to the graphical nature of the Newton environment. This chapter introduces the concepts and terminology used in Newton programming and outlines the software development process.
Terms and Concepts

Views are the basic building blocks of most applications. The individual items on the Newton screenradio buttons, for exampleare all views, and there may be views that are not visible. You lay out views using NTKs graphical editor. When you draw a view, NTK creates a template, that is, a data object that describes how the view will look and act on the Newton. You build your application from a collection of templates that describe the applications elements.
Terms and Concepts
2-1
CHAPTER
A template is a frame, the basic data structure in NewtonScript. A frame is an object containing a collection of named data references called slots. You dene a views characteristics and behavior by specifying the contents of the slots in its template. You use the NewtonScript programming language to write the code that controls the behavior of a view. NewtonScript is an object-oriented language developed for the Newton. It is described in The NewtonScript Programming Language. Views are created from templates when your application executes on the Newton. The process of making an object, such as a view, at run time, from a template, is called instantiation. A view has two parts: the visual object you see on the screen, and a frame in memory containing transient data used at run time. This frame is sometimes called the view frame. Note that applications can also include non-graphical components, such as communication services, that have no visible manifestations. Like views, these objects are described by templates and are instantiated at run time into a frame that exists in working RAM. Newton applications are stored on ROM-based PCMCIA cards or in a protected part of the Newton memory. Unlike some computers, the Newton does not copy an application (in this case, a collection of templates) into working RAM when executing it. Therefore, templates are read-only objects. Views are their dynamic, writable counterparts. When the Newton instantiates a view, it creates a view frame in working RAM. The view frame contains a pointer to the template. Information is read from the template as needed. If a value changes at run time, a slot is added to the view frame, and the new value is stored there. This memory-use strategy allows applications to use relatively small amounts of working RAM. This architecture also makes available to your application all templates built into the Newton ROM. When you use a view template from the NTK palette (described in Chapter 4, Using the Newton Toolkit), your application
2-2
Terms and Concepts
CHAPTER
doesnt have to contain the full template. Instead, NTK references the templates in the Newton ROM, and places only your modications in the application. The Newton Programmers Guide contains a full description of the Newton view system and the templates and functions you use when programming a Newton application.
The NTK Development Process

You manage an application under development as an NTK project, that is, the collected les and specications NTK needs to build a data package that can be downloaded to and executed on the Newton. The section Setting Up a Project beginning on page 4-1 describes how you organize a project in NTK. You lay out an applications visual interface with NTKs graphical editor and a palette of view templates. The graphical editor creates layout les, that is, Macintosh les containing the templates that describe the applications views. The section Laying Out Views beginning on page 4-11 describes the graphical editor and palette. You use the NTK browser to search through and edit the templates in a layout le. The section Browsing and Editing Templates beginning on page 4-26 describes the NTK browser. Once youve programmed your application, you use NTK to build a package, that is, a data object that can be installed on the Newton. The sectionBuilding a Project beginning on page 4-37 describes the build cycle. You also use NTK to download the package to the Newton. You can study and alter your application while its running with the Inspector, NTKs interactive debugger. Chapter 5, Debugging, describes the Inspector. Figure 2-1 illustrates the application development process.
2-3
CHAPTER
Figure 2-1
The Newton application development process
2-4
CHAPTER
A Quick Tour of NTK
This chapter illustrates the Newton application development process and introduces the major components of NTK. You can follow this tutorial to create, build, download, and examine a simple application. The tutorial illustrates
n n n n n n
starting up NTK setting up an application project laying out the applications visual interface coding the application building an application package and downloading it to a Newton inspecting the application while its running.
Note
This tutorial assumes that youre running NTK on a Macintosh with a serial connection to a Newton, as described in Chapter 1, Installation and Setup. u The next chapter, Using NTK, describes the primary components of NTK in approximately the same order theyre introduced in this tutorial. You might want to read the two chapters in parallel.
3-1
CHAPTER
A Quick Tour of NTK
Starting Up NTK
1. If NTK is not already running, 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.
Setting Up a New Project

You build a Newton application from a collection of les, which you coordinate 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 project name from Untitled Project-1 to Hello.prj.
3-2
Starting Up NTK
CHAPTER
A Quick Tour of NTK
3. Click Save. NTK displays the blank project window.
4. Choose Settings from the Project menu. NTK displays the Project Settings dialog box, through which you specify the information NTK needs to build an application package.
NTK sets up default name and symbol strings based on the name of your project. 5. Change the symbol to Hello:TUT
Setting Up a New Project
3-3
CHAPTER
A Quick Tour of NTK
6. Change the package name to Hello:TUT 7. Click OK. Setting Up a Project beginning on page 4-1 describes all the elds in the Project Settings dialog box.
Starting a Layout File and Adding It to the Project

NTK provides a graphical editor for arranging the visual elements of your application. You typically start with the application base view, the screen image that appears when the user starts the application. The application base view is the ancestor of all other views in an application. Its the hub of the application, both visually and structurally. 1. Choose New Layout from the File menu. NTK displays a layout window and a palette of view templatesprotos, view classes, and a special NTK element called a linked subview illustrated in Figure 3-1. The buttons on the palette represent the view templates that are built into the Newton. The default layout window represents the screen of the Newton MessagePad. 2. Press and hold the mouse button with the pointer on the Selection popup menu. NTK displays the names of all the view templates on the palette. For faster identication, protos appear in the pop-up menu without the proto prefix. 3. Release the mouse button, and move the pointer over the buttons on the palette. The name visible in the Selection menu changes as you move the pointer over the buttons. The name of each template appears when the pointer is over its button. You can select a template by either clicking its button or choosing it from the Selection pop-up menu.
3-4
CHAPTER
A Quick Tour of NTK
Figure 3-1
Layout window and palette
Selection pop-up menu User-dened proto pop-up menu View alignment buttons
View template buttons
4. Using either the buttons or the pop-up menu, select protoApp, which appears as App in the pop-up menu.
The name App now appears in boldface in the Selection pop-up menu; only the selected entry appears in boldface. The protoApp denes a view with a few basic application features: a title bar, a status bar, and a close box.
3-5
CHAPTER
A Quick Tour of NTK
Most applications use either the protoApp proto or the clView view class for the application base view. For descriptions of the system-dened protos and view classes, see the chapters Working With Proto Templates and Working With View Classes in the Newton Programmers Guide. 5. Draw the base layout view, positioning it approximately as shown here.
The rectangle you dene here determines the size and location of the application on the Newton screen. NTK labels your new layout view protoApp, using the name of the proto from which it was constructed. 6. Choose Template Info from the Browser menu. NTK displays the Template Info dialog box, which lets you name and declare view templates. (Declaring a view allows you to access the view symbolically from another view, as described briey in Naming and
3-6
CHAPTER
A Quick Tour of NTK
Declaring Views beginning on page 4-21 and in more detail in the Views chapter in the Newton Programmers Guide.)
7. Type the name baseView, and then click OK. 8. Save the layout le by choosing Save As from the File menu, typing the name main Hello.t, and then clicking Save. 9. Choose Add Window from the Project menu. NTK adds the layout main Hello.t to the project le. 10. Activate the project window (by clicking the title bar) to see the list of les in the project, which at this point includes only the le main Hello.t.
NTK designates the rst layout le you add to a project the main layout le, that is, the layout le containing the application base view. The bullet next to the lename marks the main layout le. You can change the designated main layout le through the Project menu. 11. Choose Save from the File menu to save the project le.
3-7
CHAPTER
A Quick Tour of NTK
Laying Out Application Elements

You lay out the elements of an application within the application base view. In this section of the tutorial, you add a view that accepts handwritten input from the user. 1. Activate the layout window, now titled main Hello.t, by clicking its title bar. 2. Using either the buttons on the palette or the Selection pop-up menu, select protoLabelInputLine.
3. Draw out a rectangle inside the application base view, imitating the size and location shown here.
3-8
Laying Out Application Elements
CHAPTER
A Quick Tour of NTK
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 by choosing the Preview command or by pressing Command-Y on the keyboard. 5. Save the layout le by choosing Save from the File menu.
Customizing a View Template

When you lay out a view, NTK creates a view template, a frame containing the named slots that dene the view. You can edit view templates with NTKs browser. The browser displays a list of templates and a list of slots within the selected template. When you select a slot for editing, the browser invokes a slot editor of the appropriate type.
3-9
CHAPTER
A Quick Tour of NTK
Editing a Slot
In this section, you change the applications title by editing the title slot in the application base view template. 1. Select the application base view by clicking within the baseView view but outside the protoLabelInputLine view. Small selection marks appear in the corners of the selected view. 2. Choose New Browser from the Window menu. NTK displays a browser window for the base view, as illustrated in Figure 3-2. The template list shows the templates for the selected view and all its children. The slot list shows the slots for the view thats selected in the template list. The slot pop-up menus list system-dened slots you can add to your templates. When you open a slot for editing, you work in the slot editor area. 3. Click protoApp:baseView to select it. NTK displays in the slot list the slots for that template. 4. Double-click the title slot to open it for editing. NTK displays the slots current contents, Application, in the editing area. 5. Select the default text and change it to Hello, world 6. Apply the change by clicking the Apply check mark in the bottom-left corner of the browser window.
Apply Revert
You can also apply a change by pressing Command-E or choosing Apply from the Browser menu. 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 change.
3-10
CHAPTER
A Quick Tour of NTK
Figure 3-2
A browser window
Template list
Slot list
Slot pop-up menus
Slot editor area
7. Save the layout le. Saving with either the browser window or a layout window active saves the layout le for the template youre editing.
Adding a Slot
You can add system-dened slots to a view through the pop-up menus labeled Specic, Methods, and Attributes, located below the slot list in a browser window.
You can also dene and add your own slots by choosing New Slot from the Browser menu, as described in Adding Slots beginning on page 4-28.
3-11
CHAPTER
A Quick Tour of NTK
In this section of the tutorial, you add a label to the applications pen-input view by adding a label slot to the view template. 1. Activate the browser window by clicking its title bar. 2. Select protoLabelInputLine from the view list by clicking it. NTK displays 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. 4. Replace the default label with the text My Message 5. Apply the change by clicking the Apply check mark (or by pressing Command-E or choosing Apply from the Browser menu). 6. Save the layout le by choosing Save from the File menu.
Building and Downloading a Package

At almost any point after youve laid out an application base view, you can build your application into a package, which you can download and run on a Newton.
Note
To download, you must have connected a Newton and installed the Toolkit App, as described in Chapter 1, Installation and Setup. u 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 places the package in a le called projectname.pkg.
3-12
CHAPTER
A Quick Tour of NTK
3. Choose Download Package from the Project menu.

Note
This tutorial assumes there is no Inspector connection open. If youve made an Inspector connection, the Inspector handles the downloading from this point. u The Macintosh reports its communication settings and prompts you to initiate the connection on the Newton. 4. Verify that the message describes your conguration. 5. Tap the Toolkit App icon in the Extras drawer on the Newton. The Toolkit App opens.
6. Tap Download Package. The Macintosh reports progress during the download. When downloading is complete, the application appears in the Extras drawer on the Newton.
3-13
CHAPTER
A Quick Tour of NTK
7. Open the application by tapping its icon.
8. Test the application by writing in the input view. 9. Close the application when youre done.
Adding a Linked Layout

As an application grows more complex, the layout window can become cluttered. You can split your application into logical modules and keep your layout windows manageable by laying out child views in separate template les and linking them into the application through an element called a LinkedSubview, available through the NTK palette. In this tutorial, you lay out a oating window in a separate layout le and link it to the application base view. You make it available to the user by adding to the base view a button that, when pressed, sends an Open message to the linked view.
3-14
CHAPTER
A Quick Tour of NTK
Laying Out a Linked View

In this section, you create a template for a linked view that displays a message when the user presses a button. 1. Choose New Layout from the File menu. 2. Choose Save As from the File menu, type the name floaterMessage.t, and click Save. 3. Choose Add Window from the Project menu to add floaterMessage.t to the project list. Add Window adds the active layout to the project list; Add File displays a dialog box that allows you to add a le from anywhere on the desktop. 4. Select protoFloatNGo from the palette.
Like all layout les, a layout le for a linked view must have a main layout viewin this case, a view based on protoFloatNGowhich is the parent of all other views in the le. 5. Draw the view, positioning it approximately as shown here.
3-15
CHAPTER
A Quick Tour of NTK
The rectangle you specify in this step denes the size and location of the linked view. 6. Choose Template Info from the Browser menu, name the view floaterLink, and then click OK. 7. Select protoStaticText from the palette.
8. Lay out the text view within the layout view approximately as shown here.
This rectangle denes the location of the static text message within the linked view.
3-16
CHAPTER
A Quick Tour of NTK
9. With the protoStaticText view still selected, choose New Browser from the Window menu. NTK displays a new browser.
10. Click protoStaticText to display the slots in that template. 11. Double-click the slot name 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, such as Hello, world, from a linked view 13. Close the browser window by clicking the close box in the top-left corner. NTK automatically applies pending changes when you close a browser window. 14. Choose Save All from the File menu to save both the layout le and the project le.
Linking a Layout
To link a separate layout le into an application, you rst add the LinkedSubview template to any view in the main layout file or in another layout le linked to the main layout le. Then you use the Link Layout item in the File menu to establish the link. 1. Activate the main layout window (main Hello.t) by clicking its title bar. 2. If the layout is in preview mode, change it to layout mode.
3-17
CHAPTER
A Quick Tour of NTK
3. Select LinkedSubview from the palette.
4. Lay out the linked subview approximately as shown here.
The placement of the linked subview doesnt matter. The position of the view itself is determined by the linked template (in this case, the floaterLink template in the layout file floaterMessage.t). 5. With the linkedSubview view still selected in the layout window, choose Template Info from the Browser menu (or press Command-I). 6. Type in the name floaterLink, but dont click OK yet. This tutorial uses the same name for the linking view and for the layout view in the external layout le because the two templates share the same place in the view hierarchy. Linking Multiple Layouts beginning on page 4-22 explains how NTK processes linked subviews and the layout les theyre linked to.
3-18
CHAPTER
A Quick Tour of NTK
7. Click the box labeled Declare To: If floaterLink had more named ancestors, they would appear in the pop-up list. In this example, only baseView is available.
Declaring the linked subview is not necessary for linking. You declare the view in this step so that the button you add in the next section can send an Open message to its sibling, the floaterLink view. 8. Click OK. 9. With the floaterLink view still selected, choose Link Layout from the File menu. NTK displays the le-select dialog box. 10. Select the lename floaterMessage.t, and then click Open. The main Hello.t layout window now reects that floaterLink is linked to the linked view floaterMessage.t.
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 its tapped. 1. With the main Hello window still active, choose protoTextButton from the palette.
3-19
CHAPTER
A Quick Tour of NTK
2. Draw the button, positioning it approximately as shown here.
The rectangle you draw in this step determines the size and position of the button on the Newton screen. All descendants of the application base view must be contained entirely within the application base view; any portions that fall outside arent visible on the Newton. 3. Use Template Info to name the new view showFloaterButton 4. Activate the 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 script slot editor and displays a skeletal function statement. 6. Insert an instruction to send an Open message to the floaterlink view, so that the text reads: func() begin floaterLink:Open(); end
3-20
CHAPTER
A Quick Tour of NTK
7. Apply the change. When you apply a change to a slot that contains NewtonScript code, NTK checks the syntax. It displays an alert if it nds any syntax errors, but it applies the change in any case. 8. Double-click the text slot to open it for editing. This slot species the text on the button itself. 9. Change the default button text to Show Linked View 10. Close the browser window by clicking the close box in the top-left corner. 11. Save the le.
Dening Your Own Proto

This section of the tutorial creates a user proto a proto dened by you, not built into the Newtonthat 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 as needed at run time.
Laying Out a Proto and Adding It to the Palette

1. Choose New Proto Template from the 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 layout base view and place other elements within it.
3-21
CHAPTER
A Quick Tour of NTK
2. Select protoRadioCluster from the palette.
The protoRadioCluster proto provides a container view for radio buttons. 3. Draw the layout base view approximately as shown here.
3-22
CHAPTER
A Quick Tour of NTK
4. Select protoRadioButton from the palette.
This proto denes a single, labeled radio button. 5. Draw a wide, shallow rectangle within the cluster view.
3-23
CHAPTER
A Quick Tour of NTK
6. Make two duplicates of the radio button (with the new radio button view selected, press Command-D twice or choose Duplicate from the Edit menu twice), and then position the buttons approximately as shown here.
7. Select the layout view, protoRadioCluster, and use the Template Info command to name it myRadioButtons 8. Save the layout le as myRadioButtonsProto.t 9. Choose Add Window from the Project menu. NTK adds the le myRadioButtonsProto.t to the project. NTK also adds myRadioButtonsProto to the User pop-up menu in the palette. 10. Choose Save All to save the project le without activating it.
3-24
CHAPTER
A Quick Tour of NTK
Using Your Proto

Once youve saved your proto and added it to the project, NTK gives you access to it through the palette. 1. Activate the main Hello.t window. 2. Click the User button to activate the User proto pop-up menu.
The proto myRadioButtonsProto is now selected. 3. Draw a view in the lower part of the application base view. Regardless of where you try to draw the new view, NTK places it where you placed the layout view for the proto myRadioButtonsproto, because the view inherits its location from its proto. You could override the inherited location by adding a viewbounds slot to the view.
4. Choose Save All from the File menu.
3-25
CHAPTER
A Quick Tour of NTK
5. Choose Build Package from the Project menu. 6. Build and download the package, as described in Using the Inspector beginning on page 3-26. You can congure NTK to download a package automatically when its built through Toolkit Preferences, described in Setting Preferences beginning on page 4-7. 7. Open the application and test the linked template and the radio buttons. Close the application when youre done.
Using the Inspector

The Inspector is an interactive debugger that lets you browse the Newton object storage system and execute NewtonScript code on the Newton.
Note
To use the Inspector, you must have installed the Toolkit App on the Newton, as described in Chapter 1, Installation and Setup. u
Connecting the Inspector

1. On the Macintosh, choose Connect Inspector from the Window menu. The Macintosh reports its communication settings and prompts you to initiate the connection on the Newton. 2. Verify that the message describes your conguration.
Note
You can make an Inspector connection only over a serial link. u 3. On the Newton, tap the Toolkit icon in the Extras drawer.
3-26
Using the Inspector
CHAPTER
A Quick Tour of NTK
The Toolkit application opens.
4. If necessary, change the connection setting. 5. Tap Connect Inspector. The Toolkit App reports that its opening the Inspector. When the Inspector connection is established, the Inspector window opens on the Macintosh.
Executing Commands
Code you enter in the Inspector window is compiled on the Macintosh and executed on the Newton. The Inspector compiles and executes your keystrokes only when you explicitly request it by selecting and entering text. If no text is selected when you press Enter, the Inspector processes the current line. 1. In the Inspector window, type: x := 1/3; 2. Press Enter. The Inspector displays a reference to the object x and its value. #441A4C1 0.333333
You can enter and execute any valid NewtonScript code in an Inspector window. The Newton always prints to the screen a reference and the value of the last statement evaluated.
Using the Inspector
3-27
CHAPTER
A Quick Tour of NTK
3. Type: GetRoot():SysBeep(); The GetRoot function returns the Newtons root view. This line sends the SysBeep message to the root view. 4. Press Enter. The Newton sounds the system beep, and the Inspector window displays a reference and the value of the statement. #1A TRUE
5. Place the two statements together on two lines: GetRoot():SysBeep(); x := 1/3; 6. Select both lines and press Enter. The Newton executes both lines but displays the reference and value of only the last statement evaluated. #44126F1 0.333333
Looking at a Frame
This section of the tutorial looks at the Hello application developed earlier in this chapter. It assumes you have built and downloaded the application at least as far as adding the linked layout and that you have not changed the Toolkit Preferences. 1. Open the Hello application on the Newton by tapping its icon. 2. Open the oating window by tapping the Show Linked View button. 3. Type in the Inspector window: debug("floaterLink");
3-28
Using the Inspector
CHAPTER
A Quick Tour of NTK
4. Press Enter. The Inspector displays the view frame for the view instantiated from the floaterLink template. #440C359 {_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}, viewCObject: 0x1108E20, base: <1>, viewFlags: 65} You can specify how many layers of child views the Debug command displays by setting the PrintDepth parameter, described in Chapter 5, Debugging. 5. Close the oater window by tapping the close box. 6. Put the insertion point anywhere in the line debug("floaterLink"); and then press Enter. The Inspector responds NIL, because the view is not instantiated.
Using the Inspector
3-29
CHAPTER
A Quick Tour of NTK
Making a Change in a Running Application

In this nal section of the tutorial, you change the name of the button while the application is running by changing the value of the text slot in its view frame. 1. Type SetValue(Debug("showFloaterButton"), 'text, "Tap Here"); 2. Press Enter. The text on the button changes to Tap Here. 3. Close the Hello application by tapping its close box, and then open it again by tapping the icon. The text reverts to Show Linked View, because the change affected only the view frame that existed while the application was running, not the view template from which the view was instantiated. For a description of the debugging commands available in the Inspector, see Chapter 5, Debugging.
3-30
Using the Inspector
CHAPTER
This chapter describes how you use NTK to

n n n n n n
set up a project establish your NTK preferences lay out an applications views with the graphical editor edit the view templates through the browser build a package debug an application with the Inspector
Setting Up a Project
You manage an application under development as an NTK project , that is, the collected les and specications NTK needs to build a data package that can be installed and executed on the Newton.
4-1
CHAPTER
NTK builds an application from

n
a project le, which contains a list of the les youve put in the project and a set of project specications the project data le, which contains your applications installation and removal scripts and any expressions youve dened for the build layout les, which contain templates for the views youve laid out in NTKs graphical editor resource les, which contain resources used during the build.
You can also use NTK to create interactive books, that is, books that can be read with the Newton Book Reader built into the Newton ROM. To make a book, you supply the text in a book le, which you can create with the Newton Book Maker application. When NTK builds a project that contains a book le, it builds a book, not an application, although a Newton book can contain a number of small application-like elements. The documentation that accompanies the Book Maker application describes interactive books and the Book Reader.
Project File
You start a project by creating a project le. When the project le is open, NTK displays the project window, which lists the les in the project. Figure 4-1 illustrates a project window. The les of type Proto and PrintFormat shown in Figure 4-1 contain customized protos and templates formatted for printing. You create a project le through the New Project item in the Project menu. You add layout les to the project through the Add Window and Add File items. You add resource les through the Add File item, and you add a book le through the Add Book File item. A project can contain no more than one book le. You build the active projectthat is, the project whose project window is openby choosing Build Package from the Project menu. The build procedure is described in Building a Project beginning on page 4-37. You can download the package to a Newton through the Download Package command.
4-2
CHAPTER
Figure 4-1
The project window, with the main layout le selected
Project Settings
You set project specications through the Settings item in the Project menu, which displays the dialog box illustrated in Figure 4-2.
Figure 4-2 The Project Settings dialog box
Application settings
Package settings
4-3
CHAPTER
Application Settings
Name Species the text that appears beneath the applications icon in the Newton Extras drawer. This eld has no effect on books, whose title is specied in the book le. Adds a slot named debug to each view that you name through Template Info in the Browser menu. The value of the debug slot is the views name. If you create your own debug slot for a view, NTK does not override that denition. Debug build also sets a constant named debugon to true. You can test the debugon constant with an if statement to conditionally compile debugging code thats to be included in the application only if Debug build is in effect. This line, for example, prints a message to the Inspector window. if debugon then print (Executing this code); When the application is compiled, the compiler removes simple conditional statements that always evaluate to nil. The example here is stripped whenever debugon is nil. Note that a compound conditional, such as if debugon and version2 then is not stripped. Species the applications unique symbol, the alphanumeric string by which the application identies itself to the Newton root view. This eld has no effect on books. At the end of the build, if youve not created a slot with the name appSymbol in the application base view, NTK creates one and places in it the symbol you specify here. If the slot exists already, NTK doesnt overwrite it. To ensure uniqueness across all third-party products, PIE DTS maintains a registry of developer signatures. Apple recommends you build your application symbols and package names from your companys registered
Debug build
Symbol
4-4
CHAPTER
AutoClose
Icon le
signature and your application name, using this convention: name :signature A developer with the signature SURF, for example, might identify a checkbook application with the symbol checkb:SURF. To register your signature, contact the registry at PIESYSOP on AppleLink or PIESYSOP, MS 305-2A 20525 Mariani Ave. Cupertino, CA 95014 Please supply this information: Company name Contact person Mailing address Phone number E-mail address First choice of signature Second choice of signature Note that your registered name and signature is publicly available unless you make special arrangements with DTS. Identies this as an AutoClose application, that is, one that closes when another AutoClose application opens. Use AutoClose unless your application has a particular need to be available in conjunction with others. (A calculator, for example, is signicantly more useful without AutoClose in effect.) Selects a resource le containing the applications icon resource. The pop-up menu lists all resource les listed in the project le.
4-5
CHAPTER
Icon name
Selects a named 'PICT' resource from the le specied in the Icon le pop-up menu. NTK uses this resource for the icon that represents the application in the Extras drawer on the Newton. NTK can use only 'PICT' resources for the icon. You can supply a mask in a 'PICT' resource whose name is the icons resource name followed by an exclamation point. If an icon is named wave, for example, NTK looks for a mask with the name wave!. (A mask is a parallel bitmap used to display the icon when its selected. If you dont supply your own mask, NTK creates one.) Instructions for creating 'PICT' resources appear in Appendix C, Resources. The selected icon appears to the right of the pop-up menus. Icons are typically 32 by 32 pixels. If you specify a larger image, its scaled to 32 by 32 in the Settings dialog box. Its displayed full size, however, on the Newton.
Package Settings
Platform Species the model of Newton on which the application will run. The Platform pop-up menu lists the platform les stored in the Platforms folder in the same folder as the NTK application. Delete old package on download Automatically removes a package with the same name before downloading a package. If you dont select this option, you must remove an old package through the Memory item in the Extras drawer on the Newton before downloading a new package with the same name.
4-6
CHAPTER
Name
Copyright
Store on Newton
Version
Copy protected
Species a package name, that is, the name of the package as it will be installed on the Newton. Each package on the Newton must have a unique name. The recommended conventions for creating package names are the same as those for symbol names, described on page 4-5. Species the content of the copyright statement embedded in the package header. This text is not displayed on the Newton. Determines whether the package is saved in compressed or uncompressed format. Compressed format takes up less space on the Newton. Uncompressed format runs faster and uses less battery power. Species the version number placed in the package. In case of conict between packages with the same name, the version number allows the Newton system software to identify the newer and older versions. This number must be an integer in the range 0 to 9999. Sets a eld in the package header that marks the package as copy-protected. The copy-protection eld is not a lock; it is a convention respected by the software that copies packages.
Setting Preferences
You can adjust your own NTK environment through the Preferences item in the Edit menu. Figure 4-3 illustrates the Toolkit Preferences dialog box.
Setting Preferences
4-7
CHAPTER
Figure 4-3
The Toolkit Preferences dialog box
Layout Settings
The layout settings control the graphical editor you use to lay out views. Grid on Turns on autogrid in new layout windows. Autogrid constrains the placement and sizing of views to align with a layout grid. You can control the resolution of the grid, and you can turn the grid on or off for an individual window, through the Layout menu.
4-8
Setting Preferences
CHAPTER
Size
Sets the initial screen size for layout windows. Regardless of the Size setting, you can customize the screen for an individual layout window through the Layout Size item in the Layout menu. Arrow keys move by Sets the number of pixels by which the selected view is moved or resized when you press an arrow key. With Shift key Sets the number of pixels by which the selected view is moved or resized when you press an arrow key while holding down the Shift key.
Browser Settings
The browser settings control the display of templates and slots in browser windows.
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; Name sorts alphabetically by proto name. Sets the text style in which the template names are displayed.
Text style
Slot List
Sort by Sets the ordering of names in the slot list. The Name option orders slots alphabetically by name; Type orders slots alphabetically by data type. Sets the text style in which the slot names are displayed. Adjusts the display to show the slot value after each slot name.
Text style Show slot value
Setting Preferences
4-9
CHAPTER
Text Views
The text view settings control the handling of text by the slot editors. Auto indent Enables automatic indenting, in which the editor automatically indents a new line to the indent of the previous line. Sets the width of a tab. Sets the text style.
Tabs Text style
Packages
The packages settings control the package-build procedure. Auto save before building package Saves all open les in the project before building a package. If any of the les havent yet been saved, NTK prompts you for lenames. Auto download after building package Automatically downloads the package to the Newton after a build.
Connection
The connection settings establish the communications protocol and port for the connection between the Macintosh and the Newton. Type Port Sets the communications protocol for the connection with the Newton. Sets the communications port for the connection with the Newton.
4-10
Setting Preferences
CHAPTER
Heap Sizes in KBytes

The heap sizes settings establish the sizes of the two NTK heaps. Main heap Sets the size of the main frames heap thats created when you launch NTK. The main frames heap holds your frame data while youre working in NTK. Note that a change to this setting doesnt take effect until you quit and restart NTK. Sets the size of the heap that holds application frame data during the build. This heap is created each time you build. It needs to be approximately the size of the package being built.
Build heap
If you run out of heap space during a build, NTK reports the problem and species which heap is too small. You can then adjust heap sizes through these settings. NTK tries to allocate additional memory from available temporary memory rst. If that fails, NTK tries to allocate memory in the application partition. If NTK reports that it cant allocate heap space, try making more memory available by quitting other applications, or increase the size of NTKs partition through the Get Info item in the Finder.
Laying Out Views

You use NTKs graphical editor to lay out views in a window that represents the Newton screen. Figure 4-4 illustrates the MessagePad layout window and the palette of components, which NTK displays when you open a layout le or choose New Layout from the File menu.
Laying Out Views
4-11
CHAPTER
Figure 4-4
Layout window and palette

Selection pop-up menu User proto pop-up menu View alignment buttons
Template buttons
The graphical editor saves the views you lay out in a layout le, which contains a hierarchy of templates. Each layout le must have a single layout view, which contains all other views in the layout. The layout view can contain any number of child views, which themselves can contain any number of child views, and so on. 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.
4-12
Laying Out Views
CHAPTER
You lay out an application by laying out views from the palette. The palette includes buttons and pop-up menus that let you add these elements:
n
view classes, the basic building blocks of view templates The view class clParagraphView, for example, is the generic text view, used for static or editable text. The view classes are built into the Newton. protos constructed from the view classes The protos, also built into the Newton, provide ready-to-use elements like radio buttons and slide controls. user protos, that is, protos you dene yourself You can base your user protos on view classes, system protos, or other user protos. linked subviews, an NTK device for bringing into the hierarchy views laid out in separate layout les. 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 Newton Programmers Guide describes the view classes and protos in the chapters Working With View Classes and Working With Proto Templates. This chapter describes linked subviews in Linking Multiple Layouts beginning on page 4-22. The view alignment buttons align selected views as illustrated on the buttons.
Drawing, Resizing, and Moving Views

You use the graphical editor to draw views using the mouse and a palette of templates.
Drawing a View
To add a view to your application, you select the template you want from the palette and then draw out the view in the layout window.
Laying Out Views
4-13
CHAPTER
You can select a template by either clicking one of the buttons or selecting an entry from one of the two pop-up menus. The Selection pop-up menu near the top of the palette contains the view classes and proto templates built into the Newton ROM. The User pop-up menu contains proto templates youve created and added to the project. You activate the selection pop-up menu by clicking the Selection button (the button with an arrow on it); you activate the User pop-up menu by clicking the User button (the button with the letter U on it). Once youve activated a component, move the cursor to the layout window. To draw a view: 1. Place the tip of the arrow cursor where you want any corner of the view to appear. 2. Press and hold the mouse button. The cursor changes to a crosshair.
Hold the mouse button while you drag the cursor to the opposite corner. 3. Release the mouse button.
The rectangle youve dened on the screen marks the location of the view as stored in the viewBounds slot in the frames template. You can anticipate different platforms by adjusting the view bounds when a view is instantiated, as described in the Views chapter in the Newton Programmers Guide.
4-14
Laying Out Views
CHAPTER
Figure 4-5 illustrates a layout window with only a layout view.
Figure 4-5
A layout window with the 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. Selection marks appear at the edges of a selected view. The selected view is the target of whatever view-editing instructions you make through the mouse or keyboard. You select a view by clicking it. To select multiple views, hold down the Shift key while clicking.
Laying Out Views
4-15
CHAPTER
Selection marks appear at the drawing edges of a view. The protoApp view illustrated in Figure 4-5 has a small border between the outline of the view and the area available for drawing; therefore, the selection marks are inset slightly.
Resizing a View
You can resize a view with either the mouse or the keyboard. To resize a view with the mouse: 1. Select the view. 2. Place the cursor on the bottom-right corner of the view. When the cursor is placed for resizing, it changes to a two-headed arrow.
resize cursor
3. Press and hold the mouse button while you drag the corner. 4. When the view is the size and shape you want, release the mouse button. You can select and resize multiple views at once. If you simply resize multiple views with the resize cursor, NTK resizes the views proportionally, so that the selected views retain their relative sizes. If you hold down the Option key while resizing multiple views, NTK resizes all the views by the same absolute amount. To resize a view with the keyboard: 1. Select the view. 2. Hold down the Option key while pressing one of the arrow keys. The Right-arrow key enlarges the view by moving the right edge one pixel to the right. The Left-arrow key shrinks the view by moving the right edge one pixel to the left. The Down-arrow enlarges the view by moving the bottom edge one pixel down. The Up-arrow shrinks the view by moving the bottom edge one pixel up.
4-16
Laying Out Views
CHAPTER
To change the size of a view by ve pixels at a time, hold down both the Shift key and the Option key while pressing an arrow key. You can set the number of pixels views are resized through the Toolkit Preferences item in the Edit menu, described on page 4-9.
Moving a View
To move a view with the mouse: 1. Place the cursor anywhere on the view (except the bottom-right corner) and press the mouse button. The cursor changes to the shape of a hand.
move cursor
2. Hold the mouse button while you drag the view, and release the button when the view is in the position you want. If you press and hold the Shift key while moving a view, NTK constrains the movement to either the vertical or the horizontal axis, depending on which direction you move in rst. To move a view with the keyboard: 1. Select the view. 2. Press any of the arrow keys. The arrow keys move the view one pixel in the direction of the arrow. You can move the view ve pixels at a time by holding down the Shift key while you press the arrow key. You can set the number of pixels a view is moved by the arrow key alone and by Shift-Arrow key through the Toolkit Preferences item in the Edit menu, described on page 4-9. You can select and move multiple views at once.
Laying Out Views
4-17
CHAPTER
Aligning Views
You can align the sides or centers of two or more views by selecting the views and clicking one of the alignment buttons on the palette.
You can perform more sophisticated alignments through the Alignment and Align items in the Layout menu. Choosing Alignment displays the dialog box, illustrated in Figure 4-6.
Figure 4-6
The Alignment dialog box
As you select various alignment options, the objects in the sample rectangle move to show the effect. Once youve set up your alignment rules through the Alignment dialog box, click Apply to apply them to the selected views. You can later choose Align from the Layout menu to apply the most recent Alignment rules to the selected views.
4-18
Laying Out Views
CHAPTER
Vertical Spacing The options to the right of the sample rectangle control vertical spacing. You can either align or distribute selected views during one alignment. You can align the tops, centers, or bottoms of selected views. When aligning tops and bottoms, NTK aligns all selected views to the top of the topmost view or the bottom of the bottommost view. When aligning centers, NTK centers all views over the line halfway between the top of the topmost view and the bottom of the bottommost view. You can distribute the selected views so that the tops, centers, or bottoms are evenly spaced, or so that the distance is the same between the tops and bottoms of adjacent views. Horizontal Spacing The options below the sample rectangle control the horizontal spacing. You can either align or distribute selected views during one alignment. You can align the left sides, centers, or right sides of selected views. When aligning left and right sides, NTK aligns all views with the view furthest to the left or right, respectively. When aligning centers, NTK centers all views over the line halfway between the outer sides of the most distant views. You can distribute the selected view so that the left sides, centers, or right sides are evenly spaced, or so that the distance between the edges of adjacent views is the same.
Ordering Views
Views are drawn on the Newton screen in the order in which they appear in the drawing list. Views that appear later in the list can obscure views drawn earlier. Within each sibling group, views are added to the drawing list in the order you lay them out in NTKs graphical editor. You can move a view one place ahead in the drawing list by choosing Move Backward from the Layout menu. You can move a view one place back in the drawing list by choosing Move Forward. You can move a view behind all its siblings in the drawing
Laying Out Views
4-19
CHAPTER
list by choosing Move To Front, and you can move a view ahead of its siblings in the drawing list by choosing Move To Back. You can also reorder views by selecting them in the browser template list and pressing Option-Up arrow (to move a view forward in the drawing list) or Option-Down arrow (to move a view back in the drawing list).
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 approximation of how the views will look on the Newton screen by choosing Preview from the Layout menu. Figure 4-7 illustrates a simple view in layout mode and preview mode. Views based on the most commonly used protos appear in preview mode much like theyll appear on the Newton screen. Text is displayed only in the default font, and a protoStaticText view can display no more than 255 characters. User protos are not displayed. You can toggle between layout and preview modes by choosing Preview from the Layout menu or pressing Command-Y. Preview mode is fully implemented for the templates protoApp, ProtoCheckBox, protoLabelInputLine, protoRadioButton, protoStaticText, protoTextButton, protoPictureView, protoSlider, clGaugeView, and protoRadioCluster.
4-20
Laying Out Views
CHAPTER
Figure 4-7 layout mode
The layout window in layout and preview modes preview mode
Naming and Declaring Views

You name and declare views through the Template Info item in the Browser menu. You must supply unique names for
n n
views that declare themselves to other views and views to which other views declare themselves.
Laying Out Views
4-21
CHAPTER
You should also name all views that youll need to identify through the browser template list. You dont need to name all viewsNTK identies unnamed views with a label based on the name of the views proto. When you choose Template Info, NTK displays the dialog box illustrated in Figure 4-8.
Figure 4-8
The Template Info dialog box, for naming and declaring views
You name a view by typing into the Name eld. You activate the Declare To pop-up menu by clicking its check box. Press and hold the mouse button with the cursor on the menu to see a list of the views named ancestors. Choose the target view from this pop-up menu. You must name a view before you can declare it. Declaring a view places a slot for that view into the template in which you are declaring it, allowing symbolic access from the parent to the child. The View chapter in the Newton Programmers Guide contains a more complete discussion of declaring views.
Linking Multiple Layouts

You can organize your application into logical modules by laying it out in multiple layout windows. You link the individual les in two steps:
4-22
Laying Out Views
CHAPTER
1. In either the main layout le or a layout le thats linked to the main layout le, lay out a small reference view, using the LinkedSubview element from the palette.
2. Link the linked subview to the external layout le by choosing Link Layout from the File menu. The section Adding a Linked View beginning on page 3-17 illustrates how to link a separate layout le into an application. If you make a link to a layout le thats not already in the project, NTK automatically adds the le to the project. If you remove a linked le from a project (with the Remove File item in the Project menu), you also remove the information about links to that le. The linked subview is a placeholder in the parent view. When the parent template is processed, the templates in the linked layout le replace the linked subview template. The name of the linked subview, however, replaces the name of the layout view in the linked le. To declare a view in the linked layout le to an ancestor in the other le, you must declare the placeholder view (the linked subview) in its parent le. Child views in the linked layout le then declare themselves to the layout view in the linked layout le; they send messages up the hierarchy by referencing the placeholder view. For example, consider a placeholder view with the name birds, in the baseView template in the main layout file. The layout view in the linked layout le is named bees, and it has a child named eggs, as illustrated in Figure 4-9. In this example, the view birds declares itself to baseView, and the view eggs declares itself to bees. To send a message to its parent, the view eggs sends the message to birds. To send a message to eggs, baseView sends the message to birds.eggs.
Laying Out Views
4-23
CHAPTER
Figure 4-9
Declaring views across linked layout les
baseView
bees
Before the build birds (placeholder) declare to eggs send message declare to
baseView
birds eggs
After the build
If you assign the same name to the placeholder view and the main layout view in the linked layout le, you dont need to remember which name to reference.
Creating User Protos

You can use the New Proto Template item in the File menu to start your own proto layout. You save the layout in a separate le and add it to the project through the Project menu.
4-24
Laying Out Views
CHAPTER
Once youve added your proto to the project, you can lay out views based on it by choosing it from the User proto pop-up menu on the palette. For compatibility with the menu, give your proto layout les lenames that start with a standard alphanumeric character; dont start lenames with punctuation, slashes, or other special characters (specically, -, !, ;, ^, <, /, or (). The section Dening Your Own Proto beginning on page 3-21 illustrates how to dene and use your own proto template. During the application build, NTK adds to the applications base view one slot for each proto template youve dened. Each slot has the name pt_filename and contains a reference to the user proto.
Creating Print Format Templates

You can use the New Print Format item in the File menu to start a print format template, that is, a template formatted for hard-copy printing. You save a print format template in a separate le and add it to the project through the Project menu. During the build, NTK processes each print format le in the project and creates a constant named layout_lename that points to the processed le. You use this constant in the format frame, which is required in the application base view of any application that prints. A format frame must contain at least a title slot and a mainFormat slot; the mainFormat slot references the format le, as illustrated in this example. myFormatFrame := { title: Print Record, auxForm: nil, textScript: attachment: _proto: mainFormat: }; 'myTextScript, true, ROM_coverPageFormat, layout_myFormat
Laying Out Views
4-25
CHAPTER
The mainFormat slot in this example references a print format layout le named myFormat. For more information on printing, see the Routing chapter in the Newton Programmers Guide.
Browsing and Editing Templates

You use the NTK browser and slot editors to customize your templates.
Browsing Templates
A browser window lets you examine the templates in a local view hierarchy and the slots within each template. You open a browser window by selecting a view and choosing New Browser from the Window menu. You can examine and edit slots in the template for the selected view or any of its descendants. If you want access to all of the templates in a layout le, choose New Browser with no view selected, with the layout view selected, or with the layout le selected in the project window. You can keep several browser windows open at once. Figure 4-10 illustrates a browser window with the viewFlags slot open for editing. The template list in the top-left corner lists the templates in the view hierarchy. The slot list to the right lists the slots in the selected template. Highlighting around either the template list or the slot list shows which is active; you can change the selection in the active window by pressing the Up arrow or Down arrow key. You open a slot for editing by double-clicking its name in the slot list. The browser then displays the slots contents in the editing area in the lower part of the window. If youve changed the selection since opening a slot, clicking on the slot-name button in the editing area restores the template and slot selections.
4-26
CHAPTER
Figure 4-10
A browser window with the view ags slot open for editing
Template list
Slot list
Movable boundaries Slot-name button
Proto pop-up menus
Editing area
Revert button Apply button
You can resize the three panes of the window by moving the boundaries with the mouse. You can customize the amount of information displayed and the text styles used in the template and slot lists through Toolkit Preferences, described in Setting Preferences beginning on page 4-7. NTK provides different editors for different kinds of slots. Figure 4-10, for example, illustrates the view ags slot editor. Editing Slots beginning on page 4-30 describes the basic slot editors; Appendix D, Slot Editors, lists the specialized slot editors The Apply and Revert buttons in the bottom-left corner allow you to apply or cancel any editing youve done to a slot since the last revert or apply. When you click Apply (or press Command-E or choose Apply from the Browser menu), NTK places any outstanding changes into the slot. NTK
4-27
CHAPTER
checks for syntax errors in NewtonScript code. It reports errors in the Inspector window but applies the changes in any case. NTK automatically applies changes to a slot when you
n n n n
open a different slot for editing close the browser window save the le in which the slot is stored build a package.
Adding Slots
You can add the slots dened by the Newton system software through the three proto pop-up menus:
n
Speciclists the proto-specic slots in the proto template on which the selected template is based Methodslists the system-dened methods, that is, the code that executes when a view receives one of the system messages Attributeslists attributes, that is, the view characteristics used by the Newton when displaying and manipulating views.
You add your own slots to a template through the dialog box illustrated in Figure 4-11, which NTK displays when you choose New Slot from the Browser menu. The name centered at the top of the windows content area (protoApp in this example) is the name of the template youre adding slots to orif the template isnt nameda label based on the name of the templates proto. You can add any of the system-dened slots through the proto pop-up menus, and you can add your own slot by typing the slot name into the Slot Name eld. Whenever the Slot Name eld contains the name of a system-dened slot, the description eld contains a brief description of the slot.
4-28
CHAPTER
Figure 4-11
The New Slot dialog box
Template name or label
Slot description eld
When youre dening your own slots, you specify a slot typewhich implies a slot editorthrough the Editor pop-up menu, illustrated in Figure 4-12. The slot types are documented in the following section.
Figure 4-12
The Editor pop-up menu in the New Slot dialog box
When youve established a slot name and editor, click Add. To dismiss the dialog box, click Done.
4-29
CHAPTER
Editing Slots
You use the ve basic slot editors listed in this section to edit slots of the types available through the New Slot dialog box. NTK also supplies specialized edtiors for editing various system-dened slots, listed in Appendix D, Slot Editors. You edit evaluate, script, and text slots with the text editor described in Editing Text beginning on page 4-32. An evaluate slot is a slot thats evaluated in place, that is, during the build when the compiled code is executed. You use evaluate slots to embed data thats available only during the project build into the templates that will be used on the Newton. The value of the slot is set to the value returned by the last statement executed. A script slot holds a function denition thats compiled during the build for execution at run time. During the build, NTK processes evaluate and script slots the same waythat is, NTK rst runs the slot contents through the compiler, and then executes the resulting code with the NewtonScript interpreter. The result for an evaluate slot is a value. The result for a script slot is a function. A text slot holds text. During the build, NTK simply places the specied text in a text slot. Figure 4-13 illustrates the initial displays for evaluate, script, and text slots.
Figure 4-13
Initial contents of evaluate, script, and text slots
Evaluate slot
Script slot
Text slot
Note that if you delete the keywords func(), begin, and end from a script slot, it becomes equivalent to an evaluate slot; conversely, if you place a function in an evaluate slot, its equivalent to a script slot.
4-30
CHAPTER
Number, Boolean, rectangle, and picture slots use editors tailored to their data. Figure 4-14 illustrates the initial display for these four slot types.
Figure 4-14
The number, Boolean, rectangle, and picture slot editors
Number slot
Boolean slot
Rectangle slot
Picture slot
A number slot can hold either an integer or a real number. If you enter an integer in the range 536,870,912 to 536,870,911, NTK stores it as type integer. If you enter an integer outside that range or a number containing a decimal point, NTK stores it as type real. A Boolean slot can hold only the value true or nil.
4-31
CHAPTER
The rectangle slot holds four integers. NTK automatically calculates the width and height. In your own rectangle slots, you can use the four integers however you want. In a viewBounds slot, the meanings of the four values depend on the value of the templates viewJustify slot, as documented in Appendix D, Slot Editors. The picture slot editor lets you place a 'PICT' resource in a slot. You specify a resource le and a named icon within that le. The File pop-up menu displays all resource les in the project. Named 'PICT' resources within the selected le appear in the Picture list. The selected picture appears in the rectangle to the right of the resource list. NTK displays the width and height in pixels. If the image is larger than the space in the editing area, NTK scales it to t, for your viewing purposes only. A pictures mask is a parallel 'PICT' resource thats used to display the image when its selected. To supply your own mask, place it as a resource in the same le, with a trailing exclamation point on the resource name and check Include Mask!. If the resource is named wave, for example, the mask takes the name wave!. If you dont supply your own mask, NTK generates a simple one automatically from the original.
Editing Text
You edit text in slots, the project data le, and the Inspector window with a text editor that follows the basic Macintosh user interface conventions:
n
The blinking cursor marks the current insertion point, that is, the place where keystrokes are inserted. You change the insertion point by moving the cursor with the mouse and clicking at the new insertion point. You select text by holding down the mouse button and dragging the cursor through the text to be selected. Double-clicking selects the word in which the cursor appears. Triple-clicking selects an entire line. The Cut, Copy, and Paste items in the Edit menu (and their keyboard equivalents: Command-X, Command-C, and Command-P) delete selected text from the slot and place it on the clipboard, copy the selected text to the clipboard without deleting it, and paste the contents of the clipboard, respectively. Keystrokes replace selected text.
4-32
CHAPTER
You can also navigate, select, and manipulate text with the arrow keys and keystroke combinations listed in Appendix A, Keyboard Text-Editing Commands. As a help mechanism, NTK supplies argument information when youre entering global functions and common messages. When you type a left parenthesis after a token thats listed in the editors internal database, NTK displays a help line in the space to the left of the horizontal scroll bar. To see the arguments for the selValue function, for example, type setValue( The help message appears in a box to the left of the horizontal scroll bar, in either the browser or the Inspector window, as illustrated in Figure 4-15.
Figure 4-15 The Inspector window with a help message displayed
Help message
The search and display are triggered by the typing of the parenthesis, not by the position of the cursor.
4-33
CHAPTER
Searching for Text in Files

The Edit menu contains a number of items that let you search for a specied string in layout les, the project data le, or an Inspector window.
Listing Instances of a String

The List item identies all instances of a string in a template le or in all template les in a project. You specify the string and the search criteria through the dialog box illustrated in Figure 4-16.
Figure 4-16
The dialog box for searching with List
Select one of the radio buttons at the top of the window to specify the les to be searched. In Layout In Project Searches only the layout le for the active browser or layout window. Searches all layout les in the open project.
4-34
CHAPTER
Select one of the four radio buttons below the string eld to specify the target of the search. Frame With Name Slot With Name Text in Slot All Searches for frames whose name contains the specied string. Searches for slots whose name contains the specied string. Searches for a slots whose value contains the specied string. Searches for the specied string in a frame name, slot name, or slot value. Finds only strings that match the capitalization of the specied string. Finds only instances in which the specied string appears as a word, that is, in which the specied string is not embedded within other text.
You can limit the search by checking one or both of the boxes. Case Sensitive Whole Word
When you click Find, NTK nds and lists all occurrences of the specied string. You can double-click any of the entries to open or activate a browser window with that entry selected. If NTK nds no instances of the string, it sounds the system beep.
Finding Instances of a String

The Find and Find Next items search through text in the active window to nd and select a specied string. Find displays a dialog box, illustrated in Figure 4-17, in which you specify the string and search specications. The Whole Word option nds only instances in which the specied string appears as a word, that is, in which the specied string is not embedded within other text. The Case Sensitive option nds only strings that match the capitalization of the specied string.
4-35
CHAPTER
Figure 4-17
The dialog for searching with Find
When you click Find, NTK nds and selects the next occurrence of the specied string. If NTK nds no instances of the string, it sounds the system beep. The Find Next item nds the next occurrence of the string specied in the most recent Find dialog box. The Find and Find Next items are available when youre editing the project data le or a slot that contains text and when youre working in the Inspector window.
Finding Slots in the Hierarchy

The Find Inherited item nds and selects in the layout le the view that contains a slot with the same name as the slot selected in the browser slot list. 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 doesnt nd the slot in any template in the hierarchy, NTK sounds the system beep.
4-36
CHAPTER
Building a Project
NTK builds a package lethat is, a le containing the application or book as it will be installed on a Newtonfrom the les listed in the project le. A package le consists of a header containing package information and one or more parts containing code and data. An application is stored in a part of type form; a book is stored in a part of type book. When a package is installed on the Newton, the Newton operating system automatically opens the package and dispatches the parts to the appropriate handlers. NTK compiles and executes NewtonScript code, and processes templates and book les, to produce a data object that can be used by the Newton. The compiler compiles the text in the various source les, and the interpreter executes the resulting code at predetermined points. The code that executes during the build creates the objects that are placed in the application package. Objects in memory during the build are not necessarily available at run time. Some of your code executes on the Newton, some on the Macintosh, and some in both places. The Newton and the Macintosh are running essentially the same interpreter, but the kinds of commands executed tend to be different. Some functionssuch as those that handle resourcesare available only on the Macintosh. The Newton Programmers Guide, which documents the other Newton programming functions, identies functions that are available only at compile time. The resource-handling functions are described in this book in Appendix C, Resources. The next section, The Build Environment, describes the les that are not explicitly in the project le but that affect the project build. The section Build Sequences beginning on page 4-46 describes the order in which les and templates are processed and steps through the processing of a template.
Building a Project
4-37
CHAPTER
The Build Environment

During the build, NTK processes the layout les you create with the NTK graphical editor and list in the project le. Before and during the build, NTK also processes a number of other special les. This section describes
n n
the global data le, which is compiled and executed when you open NTK the project data le, which is compiled and executed at the beginning of a build the platforms les, which contain platform data and utility functions.
This section also describes the constants and variables you can use to access and manipulate les during the build.
Global Data File

The global data le is an adjunct to NTK. You can place in it NewtonScript code that you want available from any project. The global data lea le with the name GlobalData in the same folder as the NTK applicationis compiled and executed once each time you open NTK. Code you place in the global data le is available at compile time to any project you build. If the compiler encounters an error in the global data le, it displays the error type, lename, and line number. When you dismiss the error dialog box, NTK quits. The prudent course is to develop code in the project data le (documented in the next section) and move it to the global data le only when its debugged. If you cannot launch NTK because of a problem in the global data le, you can bypass it by removing the le from the folder. You can create and edit a global data le with any application that can produce simple text les.
4-38
Building a Project
CHAPTER
Project Data File

The project data le is an adjunct to your projectits a way to make declarations available to your project at compile time. NTK compiles and executes the project data le as the rst step in the build. The project data le is stored in the same folder as the project le. You create and edit the project data le by choosing Project Data from the Project menu. You can place in the project data le
n
a script named InstallScript, which is run when the package is installed on the Newton a script named RemoveScript, which is run when the package is removed other valid NewtonScript code.
This example illustrates a simple project data le that denes constants for the application symbol and package name and denes install and remove scripts that register an application with the system Find and Intelligent Assist services. constant kAppSymbol := '|Hello:TUT|; constant kPackageName := "Hello:TUT"; InstallScript := func(partFrame) begin SetAdd( FindApps, kAppSymbol, true ); partFrame.result := regTaskTemplate(myTemplate); end; RemoveScript := func(partFrame) begin SetRemove( FindApps, kAppSymbol ); unRegTaskTemplate(partFrame.result); end;
Building a Project
4-39
CHAPTER
Dening constants in the project data le makes them available to code thats executed during the application build. Build Sequences beginning on page 4-46 describes the build sequence in detail. To access a variable from the project data le in a run-time script, place a reference to it in an evaluate slot, described on page 4-30. You can use the NewtonScript constant syntax or the compile-time function DefConst to dene constants and initialize them in your project data le, as described in the section NewtonScript Code on page 4-41. InstallScript The install script is an optional script thats executed when a package is installed on the Newtonwhen the card containing it is inserted or when the package is downloaded. After NTK processes the project data le, it looks for a variable with the name InstallScript. If one exists (that is, if youve dened an install script in your project data le), NTK places it in the package as the install script for the part. The install script is a function with one argument: 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.
RemoveScript The remove script is an optional script that runs when your application is removed from the Newtonwhen the card containing it is removed, when you remove a package through NTK, or when the user removes your application through Memory Preferences. After NTK processes the project data le, it looks for a variable with the name RemoveScript. If one exists (that is, if youve dened a remove script in your project data le), NTK places it in the package as the remove script for the part.
4-40
Building a Project
CHAPTER
The remove script is a function with one argument: RemoveScript(partFrame) partFrame The part frame for your application. The RemoveScript runs after an applications card has been removed. The theForm slot in partFrame therefore contains an invalid reference. NewtonScript Code NewtonScript code in your project data le is compiled and executed at the beginning of a project build. You use it to create objects that you want available throughout the build. You can use the NewtonScript constant syntax to create constants with literal values for use throughout your project. The sample project data le on page 4-39, for example, creates constants for the applications symbol and package name: constant kAppSymbol := '|Hello:TUT|; constant kPackageName := "Hello:TUT"; You can use the compile-time function DefConst in your project data le to create constants and initialize them with arbitrary expressions. DefConst (sym, expr) sym expr A symbol that names the value An expression that denes the value of the symbol
The DefConst function creates a constant referenced by the specied symbol and with the specied expression value. The DefConst function is available only at compile time. You can use DefConst to make compile-time values available at run time without adding a slot to the application base view. You could incorporate your own resource, for example, by calling GetPictAsBits in a denition: refNum := OpenResFileX("HD:NTK:HappyProject:Joy.rsrc"); DefConst('kWren,GetPictAsBits("Wren", true)); CloseResFileX(refNum);
Building a Project
4-41
CHAPTER
You can access the bits from within the application templates by sending the CopyBits message: :CopyBits(kWren,5,5,modeMask); Functions you dene with DefConst can be called with the NewtonScript call syntax or the Apply function. You could, for example, define a function with the symbol kFunction: DefConst('kFunction,func(x,y) x + y); You could then call the function within your application, without regard to inheritance, with call kFn with (2,40); The DefConst function accepts any valid expression that can be evaluated at compile time.
Variables and Constants

NTK denes a number of variables and constants that you can use to access les and templates during the build. HOME Variable NTK denes a variable called HOME that contains the pathname of the folder containing the open project le. You can use this variable to reach other les within the same folder during the build. This line, for example, opens a resource le rNum = OpenResFileX(HOME & "myResources.rsrc"); Layout-File Constants and Variables When NTK nishes processing a layout le (that is, a standard layout le, a print format layout le, or a user proto layout le), it creates a constant named layout_lename that references the view hierarchy dened by that le. You can use the layout-le constant in conjunction with the .form
4-42
Building a Project
CHAPTER
command in the BookMaker application to incorporate the layout les for any small, application-like elements included in your book les. The .form command, which is documented in the manual that accompanies the Book Maker application, requires the height and width of the layout base view, which you can get from the viewBounds slot for the view as displayed in the browser. You can also use the layout-le constants in other situations where you need a reference to the template, as long as youre careful to use the constant only after its created. When NTK processes a print format layout le, it also creates a variable named printFormat_lename , which also references the view hierarchy dened by that le. This variable is redundant with the layout_lename constant; it remains for backward compatibility with earlier releases.
Platform Files
The platform lesstored in a folder named Platforms in the same folder as NTKcontain data tailored to different Newton products and a collection of Newton system denitions. The platform les also contain a number of utility functions and denitions for constants that reference them. The constant that represents a function is the function name with the prex k and the sufx func (that is, kfunctionnamefunc). The release notes for each platform le list the functions in that le. The functions are available at compile time; you can make them available at run time by incorporating them into your application in one of two ways:
n
In your application base view, dene an evaluate slot with the same name as the function and initialize it to the corresponding constant. To use the NewInfo function, for example, you create a slot named NewInfo and set its value to kNewInfofunc. You can then call the function by sending a message to the application base view. Call the function with the NewtonScript call syntax or the Newton Apply function. This strategy saves space and time, because it does not require a slot in the base view and avoids inheritance lookup; it also works in code that doesnt have access to your base view, such as the
Building a Project
4-43
CHAPTER
remove script. This strategy does not work for functions used as methods, which must be invoked using message sending. The Newton Programmers Guide identies which functions are used as methods and which are global functions.
Resources
NTK recognizes a number of functions that let you incorporate Macintoshstyle resources into your application. These functionsfor opening and closing resource les and retrieving resources from themare available on the Macintosh during the build, but theyre not available on the Newton at run time. Therefore, you can manipulate resources only in code thats executed only during the build. You typically manipulate resources in the project data le. You supply resources in resource les that youve added to the project le through the Add File item in the File menu. You open a single resource le with the OpenResFile function; you open multiple resource les with the OpenResFileX function. You close resource files with the CloseResFile and CloseResFileX functions. NTK supplies the GetPictAsBits function for handling 'PICT' resources and the two functions GetSound and GetSound11 for handling 'SND ' resources. You can use the functions GetResource and GetNamedResource to retrieve any other resources that your code can handle. The following code in the project data le, for example, opens a resource le named named Joy.rsrc, retrieves 'PAT ' and 'SND ' resources, and closes the resource le. refNum := OpenResFileX(Home & "Joy.rsrc"); gCheckerBoard := GetNamedResource("PAT ","checkerBoard", 'pattern); gChickadee := GetSound("chickadee"); CloseResFileX(refNum);
4-44
Building a Project
CHAPTER
To embed the resources in your application, place them in evaluate slots in your application base view. In this example, two evaluate slots are initialized to the compile-time global variables gCheckerBoard and gChickadee. See Appendix C, Resources, for a more complete description of the functions that handle resources. Note that NTK automatically handles 'PICT' resources that you use for your applications icon and in picture slots in your templates. For a description of the picture slot editor, see Editing Slots beginning on page 4-30. You can create resource les on the Macintosh with the ResEdit application, available from the Apple Programmers and Developers Association (APDA). You can draw your pictures in any graphics program, and then paste them as 'PICT' resources into a resource le in ResEdit.
Merging Packages
NTK builds one part from the les listed in a single project le. After it assembles that part, it examines the folder in which the project le is stored for other package les with the names include.pkg[n ]. If it nds any, NTK copies the parts in those packages and includes them in the project package. You can place any number of other packages in the folder. The rst package to be included has no number in its lename, and subsequent packages have the next highest integer appended. That is, to include two other packages in a build, put the packages in les with the names include.pkg and include.pkg1. Once the progression is broken (when, for example, NTK nds no le named include.pkg2), NTK stops searching.
Building a Project
4-45
CHAPTER
The added parts come before the newly created part in the package. If, for example, the project folder contains two package les, include.pkg containing parts A and B, and include.pkg1 containing a single part C, the nal package contains four parts, in this order: A, B, C, new part.
New part Project les Part generated in this build Part A Part A Part B include.pkg include.pkg1 Part C New part Part generated in this build Part B Part C New part Final package
The package attributes of the packages being merged are ignored; the nal package contains only the package attributes established for the current build through the Project Settings dialog box. Name, symbol, and other part settings remain intact for each part. The order of the parts in the package determines the order in which the Newton operating system dispatches the partsit determines, for example, the order in which the install and remove scripts are executed.
Build Sequences
This section describes
n
the order in which les are processed when NTK builds an application or a book and how NTK processes a layout le
4-46
Building a Project
CHAPTER
Building an Application
When you choose Build Package from the Project menu, NTK rst scans the project le to determine whether it contains a book le. If not, NTK builds an application, following this sequence: 1. Compile and execute the project data le. Memory objects created by the project data le are available to the templates processed during the rest of the build. 2. Process the templates in the print format les, as described in the section Processing a Layout File on page 4-49. As it processes each print format le, NTK creates a constant with the name layout_lename , as it does for every layout le it processes. It also creates a variable with the name printformat_lename. 3. Process the templates in the layout les (starting at the main layout and recursively processing the view hierarchy), as described in the section Processing a Layout File on page 4-49. After it processes each layout le, NTK creates a constant with the name layout_filename that contains a reference to the layout view for that file. Note that when NTK reaches a template thats based on an unprocessed user proto, it must process rst the proto and then the template. Whenever it adds a user proto to an application, NTK places in the application base view a slot with the name pt_lename that contains a reference to the user proto. NTK also creates the layout_lename constant when it processes a proto le, as it does for every layout le it processes. 4. Process any unprocessed user protos. This step incorporates into the application any protos youve supplied for creating views at run time only. As usual, NTK creates the layout_lename constant for each proto le. NTK always processes the main layout le rst and processes other layout les as they are encountered in the view hierarchy. Print format les are processed before all other layout les but in no guaranteed order among themselves.
Building a Project
4-47
CHAPTER
Building a Book
When you choose Build Package from the Project menu, NTK rst scans the project le to determine whether it contains any book les. If it does, NTK builds a book, following this sequence: 1. Compile and execute the project data le. Memory objects created by the project data le are available to the templates processed during the rest of the build. 2. Process the templates in the print format les, as described in the section Processing a Layout File on page 4-49. After NTK processes a print format layout le, it creates a constant with the name layout_lename , as it does for every layout le it processes. NTK also creates variable with the name printformat_lename that contains a reference to the view hierarchy dened by that le. 3. Process all top-level layout lesthat is, those that are not linked as subviews into other layout lesas described in the section Processing a Layout File on page 4-49. Note that the layout les linked as subviews are processed as part of the processing of the templates that contain them. After it processes each layout le, NTK creates a constant with the name layout_filename that contains a reference to the file. Note that when NTK reaches a template thats based on an unprocessed user proto, it must process rst the proto and then the template. NTK also creates the layout_lename constant when it processes a proto template le. 4. Process any unprocessed user protos. This step incorporates into the book any protos youve supplied for creating views at run time only. As usual, NTK creates the layout_lename constant for each proto le. 5. Compile and execute the book le.
4-48
Building a Project
CHAPTER
Processing a Layout File

When NTK processes a layout le, it starts by processing the template for the layout view, the parent of all other templates in the le. In the course of processing a template, NTK processes all of its children. Therefore, the processing of a layout le begins and ends with the layout view, which is the rst template in a le whose processing is started and the last template whose processing is completed. After it nishes processing the template for the layout view, NTK creates the constant layout_lename , which contains a reference to the view hierarchy dened by that le. NTK processes each template in four steps: 1. Check the proto or viewclass slot, if one is present. If the template is based on an unprocessed user proto, process that proto. 2. Compile and execute code in the beforeScript slot, if its present. Memory objects created in the before script are available to evaluate slots in the template and its descendants. The beforeScript slot exists only during the build and only during the processing of the current template; the beforeScript slot does not appear in the frame that results from the processing of a template. The beforeScript and afterScript slots let you execute code specic to a template during the build. You can use the beforeScript slot to dene functions and data that will be available during the processing of a single template, the same way you use the project data le, described in Project Data File beginning on page 4-39, to dene functions and data that will be available during the entire build. 3. Process the template itself: n create the template and add the proto or view class slot n create the slots altered or added through the browser As it creates each slot, NTK establishes the slots value. When it creates an evaluate or script slot, NTK compiles and executes any NewtonScript code in the slot. The result for a slot that contains code is a value. The result for a slot that contains a function statement is a function.
Building a Project
4-49
CHAPTER
create the stepchildren slot (described in the Views chapter of the Newton Programming Guide) process the templates children, adding each child to the stepchildren array as its created.
4. Compile and execute code in the afterScript slot, if its present. 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 existing slots. This code in an afterScript slot, 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. Application Settings beginning on page 4-4 documents the Debug build option. s WARNING The thisView variable gives your after script access to any slot in a view. Use it carefully. s The code in the afterScript slot is not part of the nal application. You can create beforeScript and afterScript slots for any view through the New Slot item in the Browser menu, documented in Adding Slots beginning on page 4-28. Create the slots as evaluate slots with the names beforeScript and afterScript.
Error Messages
If NTK cannot build a package because of problems with the projectif, for example, it could not nd a referenced user protoit displays an error message describing the problem. NTK often displays additional information in the Inspector window, if its open. If NTK encounters errors in the NewtonScript code contained in the project, or if it encounters an error in downloading, it displays an error message with the error number. You can look up error numbers in the Errors appendix in the Newton Programming Guide.
4-50
Building a Project
CHAPTER
Debugging With the Inspector

The Inspector is an interactive debugging environment that lets you study your application and make changes while its executing. You can make an Inspector connection through the Toolkit App running on a Newton attached to the Macintosh by serial cable, as described in Chapter 1, Installation and Setup. You communicate with the Newton through the Inspector window, illustrated in Figure 4-18.
Figure 4-18
Inspector window
Help eld Trace Off button
4-51
CHAPTER
You make a connection to the Newton with the Connect Inspector item in the Windows menu. You can save the contents of the Inspector window through the File menu, and you can open the Inspector window without connecting to the Newton by choosing Open Inspector from the Windows menu. You edit text in the Inspector window with the editor described in Editing Text beginning on page 4-32 and in Appendix A, Keyboard Text-Editing Commands. The help eld displays the parameters and return values of functions and common messages when you type a left parenthesis after a function or message name. The Trace Off button turns off a stack trace, as described in Chapter 5, Debugging. You execute code youve typed in the Inspector window by selecting the text and pressing Enter. If you press Enter with no text selected, the Newton executes the current line. The Inspector window gives you access to the NewtonScript interpreter and the object store on the Newton. You can call any of the debugging functions described in Chapter 5, Debugging, and you can execute any valid NewstonScript code in the Inspector. During a project build, and when youre editing templates in the browser, NTK displays warnings and error messages in the Inspector window. Using the Inspector beginning on page 3-26 is a tutorial that introduces the Inspector.
4-52
CHAPTER
Debugging
This chapter describes the debugging facilities that you can use with the Newton PDA and the Newton Toolkit to inspect and debug your applications. This chapter describes
n n
the Inspector, the interactive debugger that is built into NTK debugging functions you can add to your NewtonScript programs for use with the Inspector common NewtonScript programming problems
The Inspector
The Inspector is an interactive debugger that lets you browse the Newton object storage system, issue debugging commands, and execute NewtonScript code on the Newton. You use the Inspector by typing commands in the Inspector window. You open the Inspector window by choosing Open Inspector from the Window menu, an you can save the contents of an Inspector window by choosing Save or Save All from the File menu.
The Inspector
5-1
CHAPTER
Debugging
You establish an Inspector connection to a Newton (and open the Inspector window if its not already open) by choosing Open Inspector command from the Window menu. You can make an Inspector connection to a Newton attached with a serial cable to the Macintosh, as described in Installing the Toolkit App on the Newton beginning on page 1-5. Once youve connected the Inspector to your Newton, you can directly execute NewtonScript statements by typing them into the Inspector window and pressing the Enter key.
Using the Inspector

You can use an Inspector connection to perform a number of debugging activities, including:
n n n n n n n
directly executing NewtonScript statements tracing the ow of execution examining the stack breaking automatically whenever an exception occurs on the Newton browsing and debugging views and other objects setting breakpoints at specic locations in your Newton program displaying memory statistics
You can type NewtonScript statements into the Inspector window to execute code on the Newton from your Macintosh keyboard. The output of any printing function calls that you have embedded in your NewtonScript programs is directed to the Inspector window. After you have connected the Inspector to your Newton and downloaded your application package, you can debug, modify, and again download your application from within the Newton Toolkit. If you select automatic downloading in your Toolkit Preferences, your modied program application is automatically downloaded into the Newton every time you rebuild it. You can then debug using this cycle:
5-2
The Inspector
CHAPTER
Debugging
1. Run your application on the Newton. The Inspector displays any output and traces execution. 2. If necessary, use the Inspectors debugging functions to determine what problems you need to address. 3. Make necessary changes to your application with NTK. 4. Rebuild your application package in NTK. 5. Return to step 1. You can interrupt the execution of your application by calling the BreakLoop function. Then, while the program is paused, you can use the other debugging functions to examine memory and the ow of control. The debugging functions are described in the section Debugging Functions beginning on page 5-16.
Tracing the Execution of Your Application

You can watch the ow of control through your application by telling the Inspector to trace the program execution. To trace the execution of every function call that occurs, type: trace := 'functions The Inspector then reports each function call with a message similar to this example. Sending TrackHilite(18070494) to #440F671 => TRUE This example shows the TrackHilite message being sent. The numbers you see are references to frames. The reference in parentheses is the argument list to the TrackHilite message. The last reference is the view to which the message was sent. The second line (which starts with =>) is the return value from the TrackHilite method. When you tell the Inspector to trace the ow of function calls, a lot of output is sent to your screen. If you want to follow the execution of your program even more closely (and generate even more output), you can tell the
The Inspector
5-3
CHAPTER
Debugging
Inspector to trace every frame and variable access. You do this by setting the value of the trace variable to anything other than nil or 'functions. Typically, you use the value true: trace := true The output you get in the Inspector window with this same message after setting trace to true looks something like this example: #1A TRUE Sending TrackHilite(18070456) to #44193C9
get #4404191 / #477.penSoundEffects = TRUE get #44193C9.viewCObject = 17864138 get #44193C9 / #38B.viewFlags = 515 set #44193C9 / #38B.viewFlags = 33554947 get #44193C9.viewHiliteScript = NIL => TRUE Sending buttonClickScript() to #44193C9 Calling Print(#600E446D) "The button has been clicked" => NIL Calling breakLoop() Sending hilite(NIL) to #44193C9 get #44193C9.viewCObject = 17864138 get #44193C9.viewFlags = 33554947 set #44193C9.viewFlags = 515 => TRUE get #44055F9 / #3B9BFD.viewIdleFrequency = 30000
5-4
The Inspector
CHAPTER
Debugging
get #44055F9 / #3B9BFD.viewIdleScript = #28F09D get #4419B41 / #4408AF1.userConfiguration = #4404191 // AND LOTS MORE OUTPUT AFTER THIS
Note
The output displayed in the Inspector window shows the internal address of each object, prefaced by the pound sign (#). You can ignore these address values. u To turn off tracing, click the Trace Off button at the bottom of the Inspector window, or type trace := nil The Inspector does not immediately attend to this statement, which means that the volumes of information appearing in your Inspector window continue to appear after you have typed the statement. Clicking the Trace Off button works almost immediately.
Examining the Program Stack

While your Newton program is paused in a break loop, you can examine the state of the program stack with the StackTrace function. A trace is displayed in the Inspector window when you type StackTrace() The trace consists of an array of activation records, each of which represents the run-time call stack and contains ve slots: class CodeBlock The class name of the frame, which is always StackFrameInfo. The name of the function for the activation record. This is generally the name of a method or of a global function. Some NewtonScript functions that do not have names show up as NIL in this slot.
The Inspector
5-5
CHAPTER
Debugging
programCounter The value of the program counter. You can ignore this. receiver The receiver for the activation record. If the receiver has a slot named debug, then that slots value is shown here. Otherwise the value will be NIL unless the receiver is a global variable, in which case, the variables name will be shown here. contextFrame An array of symbols. There is one symbol for each parameter to the frames function and one symbol for each local variable. The parameters are listed rst, followed by the local variables. This example shows a simple stack trace: [{class: StackFrameInfo, CodeBlock: NIL, programCounter: 2, receiver: NIL, contextFrame: []}, {class: StackFrameInfo, CodeBlock: "functions.breakLoop", programCounter: NIL, receiver: NIL, contextFrame: []}, {class: StackFrameInfo, CodeBlock: buttonClickScript, programCounter: 5, receiver: NIL, contextFrame: []}, {class: StackFrameInfo, CodeBlock: viewClickScript, programCounter: 10, receiver: NIL, contextFrame: [unit]}]
5-6
The Inspector
CHAPTER
Debugging
The entire trace is enclosed in square brackets ([ and ]). Each stack frame is enclosed in curly brackets ({ and }). The most recent function activation record appears at the top of the output, which means that you can trace through the sequence of functions by tracing backwards through the CodeBlock values. In the example above, the ow of functions is as follows: NIL->functions.breakloop->buttonClickScript-> viewClickScript The rst two elements of the array represent the activation records for the StackTrace call and for the BreakLoop call that halted execution prior to the stack trace. These two elements are generally not of value to you. To examine the values of parameters and local variables in the stack frames, you need to know how many parameters each function requires. You can then count the parameters to get to the local variables. For example, suppose you have a function myFcn: myFcn: func(value) begin local x := 2; breakloop(); return value+x; end If you call the function and print out a stack trace from the break loop, you see this frame in the output: {class StackFrameInfo, CodeBlock: myFcn, programCounter: 6, receiver: "vars.myFrame", contextFrame:[value,x]}
The Inspector
5-7
CHAPTER
Debugging
Because you have dened myFcn with one parameter, you know that value is a parameter and that x is thus a local variable. The StackTrace function is described on page 5-18. Code blocks, receivers, and context frames are described in the chapter Functions in The NewtonScript Programming Language .
Breaking for Exceptions

You can raise exceptions in your NewtonScript programs to modify the ow of execution when certain conditions arise. You can also dene exception handlers to take action upon certain conditions. The Inspector automatically reports exceptions that are raised by your code or by the Newton system software. NewtonScript exception handling is described in The NewtonScript Programming Language. The Inspector reports on all exceptions that occur during the execution of your Newton application. You can optionally tell the Newton to automatically interrupt the execution of your program whenever an exception occurs. To do so, type breakOnThrows := true Then, whenever an exception occurs, the Newton stops execution and allows you to examine the stack, debug frames, or perform other debugging tasks in the Inspector. To resume execution of your Newton application, type ExitBreakLoop() You can disable the interruption of execution whenever an exception is raised by typing breakOnThrows := nil The Inspector continues to report each exception that is raised, but your program is not interrupted.
5-8
The Inspector
CHAPTER
Debugging
Displaying Information in the Inspector Window

You can display the value of your Newton objects in the Inspector window by typing the object name. For example, if you type: myView.text Then youll see in the Inspector window the value of the slot named text in the view referenced by myView. You can display object values from within an application by embedding the Print, Write, and Display functions. Each of these functions takes an object and displays the objects value. The Print function displays an object and adds a newline character. The Write function is like the Print function, except that it does not append a newline character to the output. The Display function is like the Write function, except that it attempts to make the output more readable by adding quote marks and similar punctuation. The following example shows the differences that result from using each of the three functions to print some text followed by the value of a slot in a view. The slot that is printed is a text slot with the value TAP HERE in a text-button view. These statements: Print("My view has the following value: "); Print(myview.text); Print("\n"); produce the following output in the Inspector window. "My view has the following value: " "TAP HERE" " " #2 NIL
The Inspector
5-9
CHAPTER
Debugging
These statements: Write("My view has the following value: "); Write(myview.text); Write("\n") produce the following output in the Inspector window. My view has the following value: TAP HERE #2 NIL These statements: Display("My view has the following value: "); Display(myview.text); Display("\n") produce the following output in the Inspector window. "My view has the following value: ""TAP HERE"" "#2 NIL The Print, Display, and Write functions are described in more detail in the section Debugging Functions beginning on page 5-16.
Printing Objects in the Inspector Window

When using the Inspector to view objects, you can set the value of the printDepth variable to control how many levels of frames are displayed. The default value of printDepth is 1; the range of values is 0 to 3. Each of the three display functions (Print, Display, and Write) produces the same output when displaying a frame in the Inspector window.
5-10
The Inspector
CHAPTER
Debugging
The following examples show the displayed results of printing a view with different print depths. This is what the results look like when printDepth is 0. printDepth:=0; print(myview) {_Parent: {#4409731}, _proto: {#600E4285}, viewCObject: 0x110957D} If you set printDepth to 1 and print the same view, you get the following results. printDepth:=1 print(myview) {_Parent: {_Parent: {#4405799}, _proto: {#600E406D}, viewCObject: 0x1108B2A, viewclipper: 17862493, base: <1>, viewFlags: 5}, _proto: {text: "TAP HERE", buttonClickScript: <CodeBlock, 0 args #600E4345>, viewBounds: {#600E4575}, viewJustify: 6, _proto: {#38B}, debug: "MyButton"}, viewCObject: 0x110957D}
The Inspector
5-11
CHAPTER
Debugging
If you set printDepth to 2, you get a great deal of information. The rst few lines of the results are shown here: printdepth:=2 #8 2 print(myview) {_Parent: {_Parent: {_Parent: {#4409D59}, _proto: {#47F}, viewCObject: 0x1107CB7, RemoveOldMeetingsForm: {#4405369}, downButton: {#44055C9}, // lots more output goes here Setting the value of printDepth to 3 adds another level of frames to the results. The beginning of those results is shown here. printdepth:=3 #C 3 print(myview) {_Parent: {_Parent: {_Parent: {ioStopping: NIL, classes: {#4403CD9}, extras: [#4407C89], navigator: {#4403E89}, AvailablePrinters: [#4403F39], international: {#4404DA1}, routing: {#4403E11}, poweroffhandlers: [#4403F61], // lots more output goes here
5-12
The Inspector
CHAPTER
Debugging
Displaying the Contents of a View

You can display the contents of a view with the Debug function. When you type Debug("myButton") the Debug function searches through the templates looking for one that matches "myButton"; if it nds one, it displays the contents of that view. The Debug function attempts to match a template by examining the value of the slot named debug in the template. The template is considered a match if it contains a debug slot and if the value of that slot starts with the specied template name. When Debug nds a match, it displays the view contents in the Inspector window and returns the view as its value. Debug prints the view using the same format as the Print function does for views. This means that the value of the printDepth variable controls how much information is displayed, as described in the section Printing Objects in the Inspector Window beginning on page 5-10. NTK automatically creates a debug slot for any named template in your project. You can also add a slot named debug to any frame in your program and assign the slot a unique name. This allows the Debug function to nd that frame. To access the view for a template in the Inspector, you call the Debug function and assign the view that it returns to a variable. For example, to access the view for a template named myButton, you type myView := Debug("myButton") You can then use myView to access the view. The Debug function is described on page 5-17.
The Inspector
5-13
CHAPTER
Debugging
Displaying the View Hierarchy

You can display the hierarchy under a view with the DV function. When you type DV(myView) the following information is displayed for the view referenced by myView and its children: name address bounds number viewFlags The name of the view or its proto template (if its based on a proto template and is not otherwise named). An internal reference to the object address. This value is prefaced with the pound (#) sign and can be ignored. The bounds frame of the view (left, top, right, bottom). A hex number that is the value of the viewFlags slot. A list of the viewFlags set for the view.
Heres an example of DV output for a text button view that has no children: MyButton #44132D9 [ 67, 67,167,183] 40000203 vVisible vReadOnly vClickable
Here is an example of DV output for a simple application view that does have children, including the view shown above: MyApp |protoTitle |protoStatus ||analogClock ||protoPicture |MyButton #4409679 vVisible #4409C89 vVisible #4409CE9 vVisible #4409D51 vVisible #4409D21 vVisible #4409D39 vVisible [ 8, 9,219,316] 10000005 vApplication vHasChildrenHint [ 65, 7,162, 23] 40000003 vReadOnly [ 8,298,219,316] 50000001 vHasChildrenHint [ 12,298, 29,315] 60000201 vClickable vHasIdlerHint [200,300,213,313] 40000203 vReadOnly vClickable [ 67, 67,167,183] 40000203 vReadOnly vClickable
5-14
The Inspector
CHAPTER
Debugging
The rst view listed is the view specied as the parameter to DV. In this case, the view is the top-level view of a simple application that includes a text-button child view. The child views are listed in hierarchical order. Each child view is preceded by one or more vertical bars to indicate where in the hierarchy the view is found. One vertical bar indicates that the view is a direct child of the parent, two bars means the view is a child of a child, and so on. The DV function is described on page 5-18.
Debugging Variables
As described in the previous section, the Inspector uses several variables to control how your debugging session operates. Table 5-1 summarize these variables.
Table 5-1 Variable
Debugging variables Value Explanation
breakOnThrows
true nil
Execution automatically breaks whenever an exception is raised. The Inspector continues to report exceptions, but does not cause an execution break. Prints tracing information whenever a function is called. Prints tracing information whenever a function is called or whenever a variable is referenced. This option generates a tremendous amount of output in the Inspector window.
trace
'functions true
nil
Disables the display of execution tracing information.

continued
The Inspector
5-15
CHAPTER
Debugging
Table 5-1 Variable
Debugging variables (continued) Value Explanation
printDepth
0 1 2 3
Sets the number of frame levels to print to 0. Sets the number of frame levels to print to 1. Sets the number of frame levels to print to 2. Sets the number of frame levels to print to 3.
Debugging Functions
This section describes the debugging functions that are built into the Newton system software. You can use these functions in the Inspector window to nd and view objects in memory, set breakpoints, and perform other debugging operations. The following functions are described briey here and in more detail later in this section.
n n n n n n n n n n n
The BreakLoop function interrupts the execution of your program The Debug function returns a reference to a named template The Display function prints an object in the Inspector window. The DV function prints out the hierarchy under a view. The ExitBreakLoop function resumes the execution of your program. The GC function performs a garbage collection on the NewtonScript heap. The GetLocalFromStack function returns the value of a local variable. The Print function prints an object in the Inspector window. The StackTrace function prints a stack trace in the Inspector window. The Stats function prints out Newton memory statistics. The Write function prints an object in the Inspector window.
5-16
Debugging Functions
CHAPTER
Debugging
BreakLoop BreakLoop() Halts execution and allows you to examine the state of your application on the Newton. Execution is halted within the frame that is currently being executed. While execution is halted, you can type NewtonScript and debugging statements into the Inspector window to examine and modify your Newton program. You can type slot names directly into the Inspector window to access or set their values. For example, suppose that you have a slot named myTotal in the current frame and that its current value is 102. If you type myTotal the Inspector displays #1BC 102
The rst number is an object system reference to the value, and the second number (the integer 102) is the value of the slot. If you want to change the value of a slot, you can use a NewtonScript assignment statement. For example, you can change the value of the myTotal slot to 211 by typing myTotal := 211
IMPORTANT
To resume normal program execution, you must use the ExitBreakLoop function, which is described on page 5-19. s Debug Debug(templateName) Scans the templates in the system looking for one with a debug slot whose value matches the value of the templateName parameter. templateName The string name of the template you want to examine.
Debugging Functions
5-17
CHAPTER
Debugging
This function scans all of the templates in the system looking for a match and returns the view for that template. If no match is found, the Debug function returns nil. The Debug function attempts to match a template by examining the value of the slot named debug in the template. The template is considered a match if it contains a debug slot and if the value of that slot starts with templateName . When Debug nds a match, it displays the view contents in the Inspector window and returns the view as its value. Debug displays the view contents using the same format as the Print function does for views. This is described in the section Displaying the Contents of a View beginning on page 5-13. Display Display(object) Displays the value of the object in the Inspector window. object An object that you want displayed in the Inspector window.
The Display function provides you with the ability to print any NewtonScript object. This function produces almost the same output as do the Print and Write functions. Display appends a newline character to its output and also adds quotation marks and other punctuation to enhance the readability. The Display function is useful for debugging, but does nothing while executing on a stand-alone Newton. The Display function always returns nil. You can see an example of using the Display, Print, and Write functions in the section Displaying Information in the Inspector Window on page 5-9. DV DV(view) Displays the contents of a view and the contents of its children in the Inspector window. DV also ashes the view on the Newton screen to provide you with a visual indication of its location. view The view object that you want to display.
5-18
Debugging Functions
CHAPTER
Debugging
The DV function always returns nil. A quick way to display the contents of a view is to use the Debug function, as described on page 5-17, to get a view object and call DV on that object. For example, the following line nds the view for the template named "myButton" and prints the contents of that view and its children: Dv(Debug("myButton")) There are three special symbols that you can specify for the view argument. These symbols are evaluated at run time:
n
'viewFrontMost returns the frontmost view on the screen that has the vApplication flag set in its viewFlags slot 'viewFrontMostApp returns the frontmost view on the screen that has the vApplication ag set in its viewFlags slot, but not including oating views (those with vFloating set in their viewFlags slot) 'viewFrontKey returns the view on the screen that accepts keys (there can be only one view that is the key receiver)
If a view is visible on the screen, DV produces a display of the view contents in the Inspector window, as shown in the section Displaying the View Hierarchy beginning on page 5-14. If the view is not visible, DV produces the following output: No View found(hidden?) ExitBreakLoop ExitBreakLoop() Exits a break loop that was invoked with the BreakLoop function and resumes normal program execution. The BreakLoop function is described on page 5-17. The ExitBreakLoop function always returns nil.
Debugging Functions
5-19
CHAPTER
Debugging
GetLocalFromStack GetLocalFromStack(level, symbol) Displays the value of the local variable symbol . The level argument species which receivers local variables you want to examine. The GetLocalFromStack function returns the value of the variable symbol as its function value. GetLocalFromStack accesses the receiver information in the activation records that are shown when you call the StackTrace function. This means that the rst two levels (levels 0 and 1) are related to the BreakLoop call and are not of value. To access a variable that is local to the current receiver, use level 2. For example, suppose that you have a simple method dened as follows: func() begin local str:="myString"; breakloop(); end When this method executes, a break loop is entered. At that time, you can type the following in the Inspector window: getlocalfromstack(2,'str) The result displayed in the Inspector window is shown here. #600E347D "myString" GC GC() Forces a garbage collection in the NewtonScript heap. The frames heap is a reserved area of system memory from which space for all NewtonScript objects is allocated by the system.
5-20
Debugging Functions
CHAPTER
Debugging
GC frees all allocated objects that are no longer referenced. The Newton system software automatically performs a garbage collection when memory is needed, so you almost never need to call this function. The one exception is when you are about to call the Stats function, which is described on page 5-22. The GC function always returns nil. Print Print(object) Displays the value of the object in the Inspector window. object An object that you want displayed in the Inspector window.
The Print function provides you with the ability to print any NewtonScript object. Print is similar to the Write and Display functions except that Print appends a newline character after displaying the objects value in the window and does not add any punctuation. It is useful for debugging, but does nothing while executing on a stand-alone Newton. The Print function always returns nil. You can see an example of using the Print, Display, and Write functions in the section Displaying Information in the Inspector Window on page 5-9. StackTrace StackTrace() Prints a stack trace in the Inspector window. The section Examining the Program Stack beginning on page 5-5 shows a stack trace and describes how to use the information in the trace. The StackTrace function always returns nil.
Debugging Functions
5-21
CHAPTER
Debugging
Stats Stats() Prints out memory statistics in the Inspector window. The NewtonScript heap is a reserved area of system memory from which space for all NewtonScript objects is allocated by the system. The Stats function returns the number of bytes of memory that are available. To get an accurate result, you need to call the GC function before calling Stats. The output of the Stats function looks like this: Free: 30608, Largest: 28384 Write Write(object) Displays the value of the object in the Inspector window. object An object that you want displayed in the Inspector window.
The Write function provides you with the ability to print any NewtonScript object. This function produces the same output as does the Print function, except that Write does not append a newline character to its output. It is useful for debugging, but does nothing while executing on a stand-alone Newton. The Write function always returns nil. You can see an example of using the Write, Print, and Display functions in the section Displaying Information in the Inspector Window on page 5-9.
5-22
Debugging Functions
CHAPTER
Debugging
Newton Programming Problems and Tips

This section describes several common Newton programming problems and provides some programming tips to help with debugging your applications. This section addresses
n n n n n n n n n n
setting the wrong slot value because of the inheritance rules forgetting to set the function value before exiting the function producing memory problems due to dangling frame references generating unexpected comparison results when a value is nil generating errors when using nil in an expression trying to resize a read-only object drawing text that is not appearing on the screen attempting to print from within communications code using global variables to examine exceptions accessing the built-in error codes and messages
Common Programming Problems

This section describes a number of common problems that developers can encounter when programming with NewtonScript.
Setting the Wrong Slot Value

You often need to set the value of slots in a view in one of the methods that you implement for the view. If you arent explicit about which values of the view you are setting, you can cause unintentional effects. This is because NewtonScript will automatically create a slot for you if you make an assignment to a slot that doesnt exist.
5-23
CHAPTER
Debugging
If the slot you are setting already exists in the view, your assignment always works properly. For example, the assignment to the slot named time in the following example always works as expected. myTemplate := { viewClass: clView, viewBounds: SetBounds(0,0, screenWidth, screenHeight), viewFlags: vApplication, debug: "myTemplate", time: 0, viewSetupDoneScript: func() time := Time() ... } If the slot you are setting does not already exist in the view, then NewtonScript creates it as a local variable within the scope of the method only. If the slot exists only in the parent of your view, its value will be set in the parent view. If these are not the results that you intend, you need to be explicit about which view you want to affect. For example, suppose that in the above view there was no slot named time and that the parent view did include a slot named time. Then, the assignment time := Time() would assign the value of the Time function to that slot in the parent view. You can use the special pseudo-variable self to make sure that the slot is created in your view if it does not yet exist. The value of self is always the current receiver. In the following example, a slot named time is created in the myTemplate view when the assignment statement is executed. myTemplate := { viewClass: clView, viewBounds: SetBounds(0,0, screenWidth, screenHeight), viewFlags: vApplication, debug: "myTemplate",
5-24
CHAPTER
Debugging
viewSetupDoneScript: func() self.time := Time() ... } Using self ensures that the slot is created if it does not exist in the current receiver. Similarly, if you want to be sure that you are accessing or creating a slot in the parent of your view, use the Parent method, as shown here: self:Parent().time := Time() For more details on how inheritance affects setting slot values, see The NewtonScript Programming Language .
Forgetting to Set the Function Return Value

In NewtonScript, every function has a value. Since you can put a return in the middle of a function, you can easily forget to return a value. If the caller expects a value back from your function and you dont assign one explicitly, the function result might be garbage. Its a good idea to make sure that every pathway through your function returns a value. For example, the following function could produce undesirable effects. diff : func(n1, n2) begin if (n1=nil) or (n2=nil) then return; if (n1 > n2) then return n1 - n2 else return n2 - n1; end In this example, if either of the parameter values is nil, the function exits without your having explicitly established the return value of the function.
5-25
CHAPTER
Debugging
Producing Memory Problems With Dangling Frame References

Another common programming problem in the Newton world is dangling frame references. As long as you maintain a reference to a child view, the Newton garbage collector cannot free the child view. If you keep many of these references around in your application, you might get the following error: Frames Out of Memory The solution is to clean up (set to nil) your child view references when you are done with the views. This allows the garbage collector to collect the memory for the view frame, thus leaving more memory available in the NewtonScript heap.
Generating Unexpected Comparison Results With nil Values

An interesting situation that you might encounter in your NewtonScript programs occurs when you mistype the name of a slot in a comparison. If you mistakenly type a nonexistent slot name, then NewtonScript considers its value to be nil, which can then generate the wrong result. For example, suppose that you are using a function like the following: MyCompareFrame: func(frame1, frame2) begin if (frame1.date = frame2.date) and (frame1.month = frame2.month) then return true; else return nil; end
5-26
CHAPTER
Debugging
Now suppose you want to compare the following two frames: frame1 := { day: 5, month: 12, }; frame2 := { day: 3, month: 12, }; You would make this call: MyCompareFrame(frame1, frame2) This generates a result of true. This is because neither frame1 nor frame2 contains a slot named date, which is what the MyCompareFrame function is comparing. The statement frame1.date = frame2.date evaluates to nil = nil which causes the function to return true. The best solution to this problem is to check both values and to explicitly handle the case when one or both is nil. You could change the function as follows. MyCompareFrame: func(frame1, frame2) begin if (frame1.date = nil) or (frame2.date = nil) or (frame1.month = nil) or (frame2.month = nil) then return nil;
// note day instead of date
// note day instead of date
5-27
CHAPTER
Debugging
if (frame1.date = frame2.date) and (frame1.month = frame2.month) then return true; else return nil; end
Using nil in Expressions

If you use a non-numeric value in a mathematical expression, youll generate an error. For example, the following buttonClickScript method generates an exception: func() begin local index:=0; local str:="myString"; print("The button has been clicked"); index := index + StrPos(str, "xyz", 0); print("Reached the end of the button click script"); end If you use this method, youll see the following output in the Inspector window: "The button has been clicked" Exception |evt.ex.fr.type;type.ref.frame|: [-48404] Expected a number. Got: {value: NIL} You get this output because the StrPos function does not nd the substring "xyz" and thus returns nil as its value. You can also generate this error if you dene a template that is based on a system proto and you forget to dene one of the required numeric slots. If the value of one of these slots is used in a computation, then an exception is
5-28
CHAPTER
Debugging
raised. For example, if you create a template based on the protoInputLine proto and do not dene the viewLineSpacing slot, an error occurs because that value is used in the viewDrawScript method of the template. Another way to generate an unexpected run-time error is to misspell a variable name in a mathematical expression. For example, the typographic error in this statement: index := indx + 1; generates the following exception: Exception |evt.ex.fr.intrp;type.ref.frame|: [-48807] Undefined variable "indx" {Symbol: indx}
Trying to Resize a Read-Only Object

This is a common and frustrating error. It is almost always caused by attempting to resize a template, which is a read-only object. The two most common cases, which are described in this section, are:
n n
trying to resize an array that is stored in a template trying to add children to a view whose stepChildren array is stored in a template.
If you include a slot in one of your frames that has an array dened as its default value, then the array is stored in the template, which is read-only. For example: myArray: [1, 2, 3, 4] When you instantiate the template at run time, a RAM-based view is created that inherits the read-only array. If you try to modify this array by adding elements to it, an error occurs.
5-29
CHAPTER
Debugging
To successfully add elements to the array, rst you need to clone it to create a RAM-based copy. You can do this with the following statement: myArray := Clone(myArray); Cloning the array copies the read-only array into RAM, creates a new myArray slot in the RAM-based view, and puts a reference to the RAM copy of the array in that slot. A resizing error can also occur with slots that contain frames and strings. The error is less common with strings since they are usually replaced rather than resized. Another instance of trying to resize an object that is read-only occurs when you dene a template that is composed of multiple sub-templates. The template contains a stepChildren array that is predened. When you instantiate the template at run time, a RAM-based view is created that inherits the read-only array. If you want to add children to the view at run time, rst you need to clone the stepChildren array, as shown here: self.stepChildren := Clone(self.stepChildren); AddArraySlot(self.stepChildren, newKidInTown); If you are not sure whether your view has a stepChildren slot, you need to use the HasSlot function. If the slot does not exist in the RAM-based view, you must clone it before adding elements.
Text Is Not Drawing

If youve passed a valid string to the MakeText function, but the text does not appear on the screen, its likely that the rectangle youve specied in the arguments to MakeText is too small. Try passing a larger rectangle to the MakeText function.
5-30
CHAPTER
Debugging
Problems with Printing and Communications

You might be having problems with the Print, Write, or Display functions in your communications code, especially if youve placed them inside of state frames. These problems occur for two reasons:
n
The serial port is already in use for other communications. Only one communications channel can be open at any time. The Print statements are generating a lot of interrupts. This interferes with the serial line and causes hang-ups in the communications.
If you need to issue a quick message from within your communications code and need to avoid calling Print, Write, and Display, you can use the system notication facility instead. For example, you could display a quick message with the following code. GetRoot():Notify(kNotifyAlert, EnsureInternal("My Comms App"), EnsureInternal("Help, I'm dying!!!")); Another technique that you can use to help detect these communications problems is to create an error array in the application base view. You can then add strings to this array from within your communications code, as shown here: AddArraySlot(GetRoot().kAppSymbol.DebugArray, "My Comms App:" && myDebugData);
Programming Tips for Debugging

This section provides several suggestions to help you add debugging code to your applications.
5-31
CHAPTER
Debugging
Using Global Variables to Examine Exceptions

If you are handling exceptions in your application, you can use the global variables shown in Table 5-2 to discover information about the exception. Note that the values of these variables are assigned by the top-level (system) exception handler, which means that you can use the values reliably only after the exception alert message has been displayed on the Newton screen.
Table 5-2 Variable Exception handling global variables Description
lastEx lastExError lastExMessage
the string name of the most recent exception that occurred on the Newton the integer error code of the most recent exception the string message associated with the most recent exception, if the exception contained a message
IMPORTANT
The system assigns the current exception values to lastEx, lastExError, and lastExMessage after the exception message has been displayed on the screen. These variables are probably not useful when you set BreakOnThrows to true in the Inspector. s
Maintaining View State

If you need to maintain the state of a view, you should store your state information in a soup. If you maintain the view state in a view frame, you could lose the state information when the view is closed. For example, you might need to maintain a state variable that tracks whether a check box is checked in a certain view. To do so, store the state variable in a soup.
5-32
CHAPTER
Debugging
Accessing the Parent of a View

Whenever you need to access the parent of a view, use the Parent function to nd the parent. For example: myParent := myView:Parent(); Do not directly reference the parent by accessing the _parent slot in the view.
Peeking Into a Soup

You can peek at entries in a soup by using a cursor to navigate through the soup. To initialize a cursor, you can use the Query function as shown here. curs := Query(uSoup,{type: 'index}) This approach is not generally recommended because it doesnt specify an index path. However, it works because all soups have an index on the _uniqueId slot, which is used as the index path.
5-33
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 (Command-N)

Opens a new, untitled layout window. You use this command to start a le containing the templates for your applications views. You name the le when you save it. Laying Out Views beginning on page 4-11 describes how to lay out views in a layout le. Starting a Layout File and Adding It to the Project beginning on page 3-4 illustrates how to start and use a layout le.
File Menu
6-1
CHAPTER
NTK Commands
New Proto Template (Command-T)

Opens a new, untitled proto layout window. You use this command to lay out your own protos. You name the le when you save it. Start proto layout lenames with an alphanumeric character; do not start with punctuation, slashes, or other special characters. Creating User Protos on page 4-24 describes user protos. Dening Your Own Proto beginning on page 3-21 illustrates how to dene and use proto templates.
New Print Format

Opens a new, untitled print-format layout le. You use this command to lay out templates formatted for printing on paper instead of displaying on the screen. You name the le when you save it. Creating Print Format Templates beginning on page 4-25 describes how you reference print format templates.
Open (Command-O)
Opens a saved layout le. The Open command displays a dialog box through which you specify the le to be opened. You open a project le and the project data le through the Project menu. You open browser windows and the Inspector window through the Windows menu.
Link Layout
Brings an external layout le into the local hierarchy, by linking the external le to a linked subview template selected in a layout window. The Link Layout command displays the standard save-le dialog box for identifying the external layout le.
6-2
File Menu
CHAPTER
NTK Commands
Linking Multiple Layouts beginning on page 4-22 describes linked layouts. Adding a Linked View beginning on page 3-16 illustrates how to link layout les.
Close (Command-W)
Closes the active window and its associated le. Close can affect a layout le, a project le, a browser window, or the Inspector window. (Closing a browser window does not close its associated le, which is closed only when the layout window for that le is closed.) If you close a window thats been edited since its le was last saved, NTK displays a dialog box that gives you a chance to save changes before closing the window.
Save (Command-S)
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 n
the layout le for the active layout window, the layout le for the active browser window, the project le associated with the project window the Inspector le, or the project data le.
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.
File Menu
6-3
CHAPTER
NTK Commands
You use Save As to name or rename a layout le and to create a new le. Save As is not available when the Inspector window or project data window is active, because you cant change those names.
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 put a copy of a le into another project.
Save All (Command-M)

Saves all open layout les, the project le, and the Inspector and project data le if theyre open. If youve not yet saved a le associated with one of the layout windows, NTK prompts you for the necessary lename. Use Save All before each project build to ensure that all les in the project contain 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. Any browser windows open on a layout le are closed when you revert the le.
Page Setup
Displays the Page Setup dialog box, which lets you specify the paper size and printing orientation for printing the active window.
6-4
File Menu
CHAPTER
NTK Commands
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 (Command-P)
Prints the le associated with the active window. When you choose Print, NTK displays the print dialog box, which identies 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 a layout. u
Quit (Command-Q)
Closes all open les and quits the Newton Toolkit. If you have made changes since saving any open les, NTK prompts you to save or discard the changes before closing the les.
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 (Command-Z)
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 NTK cannot undo the last operation, this command reads Cant Undo and is disabled. You cannot undo changes to a slot after youve applied them.
Edit Menu
6-5
CHAPTER
NTK Commands
Cut (Command-X)
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 (Command-C)
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 (Command-V)
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 (Command-D)
Makes a copy of the currently selected view or views and places the copy slightly offset from the original in the same parent view.
Select All (Command-A)

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).
6-6
Edit Menu
CHAPTER
NTK Commands
Select Hierarchy
Selects all child views of the selected view or views 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 template list. Shortcut: Double-click on a template name in a browser window to select the corresponding view in its layout window. You can also use Select in Layout to select invisible or hidden views.
List (Command-L)
Finds and lists instances of a string in the active layout le or in all layout les in a project. The List command displays a dialog box, illustrated in Figure 6-1, in which you specify the string you want to nd and select search specications.
Figure 6-1
The dialog for searching with List
Edit Menu
6-7
CHAPTER
NTK Commands
Listing Instances of a String beginning on page 4-34 describes the settings in the List dialog box.
Find (Command-F)
Finds a character string in the active text window. The Find command displays a dialog box, illustrated in Figure 6-2, in which you specify the text youre interested in and a pair of search specications.
Figure 6-2
The dialog for searching with Find
The Find command is available only when a text window is active or a text slot is open for editing. Finding Instances of a String beginning on page 4-35 describes the Find dialog box.
Find Next (Command-G)

Finds the next instance of the character string and search criteria specied in the last use of the Find command, which is documented in Finding Instances of a String beginning on page 4-35.
6-8
Edit Menu
CHAPTER
NTK Commands
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 NTK doesnt nd the selected slot there, the search continues up the parent hierarchy to the les layout view (that is, NTK does not search across linked layouts). 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 doesnt nd the slot in any template in the local hierarchy, NTK sounds the system beep.
Newt Screen Shot

Places a bitmap of the Newton screen on the Macintosh Clipboard. This item is available only when the Inspector is connected.
Show Clipboard
Opens the Clipboard window.
Toolkit Preferences
Displays the Toolkit Preferences dialog box, illustrated in Figure 6-3, through which you set various characteristics of the Toolkit. When you click OK, NTK stores your current settings in a le name Newton Toolkit Preferences in the system Preferences folder. The elds in the Toolkit Preferences dialog box are described in Setting Preferences beginning on page 4-7.
Edit Menu
6-9
CHAPTER
NTK Commands
Figure 6-3
The Toolkit Preferences dialog box
Project Menu
You use the project menu to manage your application project.
6-10
Project Menu
CHAPTER
NTK Commands
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.
Open Project
Opens an existing project le. You can have only on project open at a time.
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. The Add File command displays a dialog box through which you specify the name and location of the le.
Add Book File

Adds a book le to the project from anywhere on the desktop. The Add Book File command displays a dialog box through which you specify the name and location of the book le. A book le is the output from the Book Maker application.
Remove File
Removes the selected le or les from a project.
Project Menu
6-11
CHAPTER
NTK Commands
Update File
Veries that all entries in the project le can be resolved to les that currently exist. When it cant resolve an entry , NTK displays a dialog box, through which you identify the correct target le. You use Update Files to update the project le when youve moved or renamed a le since adding it to a project.
Build Package (Command-1)

Builds a package, including the les listed in the project le and following the specications in Project 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. The sectionBuilding a Project beginning on page 4-37 describes how NTK builds a package.
Download Package (Command-2)

Downloads the package le for the open project to a Newton. You must install the Toolkit App on the Newton, as described in Chapter 1, Installation and Setup, before you can download a package to it.
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.
6-12
Project Menu
CHAPTER
NTK Commands
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 prior to downloading the Toolkit App.
Mark as Main Layout

Designates the selected le in the project window as the main layout le that is, the layout le whose base view is the application base view. This item does not affect book projects, because book projects have no main layout le.
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.
Settings
Displays the Project Settings dialog box, illustrated in Figure 6-4, through which you establish the project specications described in Project Settings beginning on page 4-3.
Project Menu
6-13
CHAPTER
NTK Commands
Figure 6-4
The Project Settings dialog box
Layout Menu
You use the layout menu to control the layout environment and manipulate views in the layout window.
6-14
Layout Menu
CHAPTER
NTK Commands
Layout Size
Displays a dialog box, illustrated in Figure 6-5, that lets you set the size of the layout in pixels.
Figure 6-5
The Layout Size dialog box
If you choose a platform from the Platform pop-up menu, NTK lls in the width and height from the information in the platform le. If you choose Custom from the pop-up menu, NTK lets you set your own values for the width and height of the layout.
Autogrid On
Turns Autogrid on and off. Autogrid constrains the corners of views to nodes on the grid. The default grid resolution is 8 by 8 pixels. You can change the resolution through the Set Grid command.
Set Grid
Opens the dialog box, illustrated in Figure 6-6, that lets you change the grid size used with Autogrid. The units are pixels.
Layout Menu
6-15
CHAPTER
NTK Commands
Figure 6-6
The Set Grid dialog box
Move To Front
Moves the selected view in front of its siblings on the screen by placing it behind its siblings in the drawing list. Ordering Views on page 4-19 describes how views are ordered.
Move To Back
Moves the selected view behind its siblings by placing it ahead of its siblings in the drawing list. Ordering Views on page 4-19 describes how views are ordered.
Move Forward
Moves the selected view one step behind other views in the drawing list, so that its drawn after the view it previously preceded. You can also move a view forward by selecting it in the browser template list and pressing Option-Down arrow. Ordering Views on page 4-19 describes how views are ordered.
6-16
Layout Menu
CHAPTER
NTK Commands
Move Backward
Moves the selected view one step ahead of other views in the drawing list, so that its drawn before the view it previously followed. You can also move a view backward by selecting it in the browser template list and pressing Option-Up arrow. Ordering Views on page 4-19 describes how views are ordered.
Alignment
Opens the dialog box, illustrated in Figure 6-7, through which you establish a view alignment scheme thats applied to the selected views when you click Apply or subsequently choose Align.
Figure 6-7
The Alignment dialog box
Aligning Views beginning on page 4-18 describes the Alignment dialog box. A subset of the alignment options appears on the drawing palette.
Layout Menu
6-17
CHAPTER
NTK Commands
Align
Aligns the selected views using the alignment scheme specied through Alignment. You can apply the simplest alignment schemes to selected views by clicking one of the alignment buttons on the drawing palette.
Preview (Command-Y)
Toggles the layout screen between layout mode 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. Previewing beginning on page 4-20 describes preview mode.
Browser Menu
You use the Browser menu to manipulate slots and to control how the browser displays templates and slots.
Template Info (Command-I)

Opens a dialog box in which you can name and declare a selected view. A view name operates as a symbol in NewtonScript. Declaring a view allows you to access it symbolically from the view in which its declared and from descendants of that view. Figure 6-8 illustrates the Template Info dialog box. Naming and Declaring Views beginning on page 4-21 describes the Template Info dialog box.
6-18
Browser Menu
CHAPTER
NTK Commands
Figure 6-8
The Template Info dialog box, for naming and declaring views
New Slot (Command-=)

Opens a dialog box, illustrated in Figure 6-9, for adding new slots to the selected template.
Figure 6-9
The New Slot dialog box
Adding Slots beginning on page 4-28 describes the New Slot dialog box.
Browser Menu
6-19
CHAPTER
NTK Commands
Rename Slot
Opens a dialog box that lets you rename the selected slot.
Figure 6-10
The Rename Slot dialog box
If the slot is open for editing, Rename Slot applies outstanding changes and closes the slot editor before changing the name. Note that changing the name of the slot does not change existing occurrences of the name in scripts. Changing the case of a name through Rename Slot changes the name.
Delete Slot
Deletes the selected slot from the view template.
Templates by Type
Lists templates alphabetically by type.
6-20
Browser Menu
CHAPTER
NTK Commands
Templates by Hierarchy
Lists templates by hierarchy, with sibling views listed in the order theyre created.
Slots by Name
Orders slots alphabetically in the browser slot list.
Slots by Type
Orders slots by type in the browser slot list.
Show Slot Values

Displays the value of each slot next to the slot name in the browser slot list.
Apply (Command-E)
Inserts into the slot changes made in a slot editor.
Revert
Discards any changes made since the last Apply, or since the slot was opened for editing if no changes have been applied.
Browser Menu
6-21
CHAPTER
NTK Commands
Window Menu
You use the Window menu to open browser windows and to open the Inspector window or connect the Inspector.
Open Inspector
Opens the Inspector without making a connection to a Newton PDA. You can have only one Inspector window open at a time.
Connect Inspector (Command-K)

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. Chapter 5, Debugging describes the commands available through the Inspector.
New Browser (Command-B)

Opens a new template browser on a layout le selected in a project window or at the level of the selected view in a layout window. You use the broser to edit templates in a layout le. Browsing and Editing Templates beginning on page 4-26 describes the browser.
6-22
Window Menu
APPENDIX

This appendix lists the keyboard commands for navigating and manipulating text in NTK slots, the project data le, and the Inspector window. You can use the keyboard to
n n n n n
specify an insertion point select text manipulate selected text delete text change the effect of the next keystroke
The keyboard text-editing commands operate relative to the current insertion point or the selected text. Editing Text beginning on page 4-32 describes the basic NTK text editor. You can reverse the last keyboard command by pressing Command-Z (Undo).
Setting the Insertion Point

You can set the insertion point with the commands in Table A-1. If text is selected when you set the insertion point, it is simply deselected.
A-1
APPENDIX
Table A-1 Motion
Moving the insertion point Keystrokes
Back one character Forward one character Down one line
Left arrow Control-B Right arrow Control-F Down arrow Control-N Option-Down arrow Up arrow Control-P Option-Up arrow Option-Left arrow Option-B Option-Right arrow Option-F Command-Left arrow Control-A Command-Option-Left arrow Command-Right arrow Control-E Command-Option-Right arrow Page down Command-Down arrow Control-V Page up Command-Up arrow Option-V Option-< Command-Option-Up arrow Option-> Command-Option-Down arrow
Up one line
To beginning of word, or back one word To end of word, or to end of next word To beginning of line
To end of line
To next page
To previous page
To beginning of text To end of text
A-2
APPENDIX
Selecting Text
You can select text with the commands listed in Table A-2. If text is already selected when you issue one of the text-selection commands, the selection is extended.
Table A-2 Selection
Selecting text with keyboard commands Keystrokes
One character back One character forward One word back One word forward Back to beginning of line Forward to end of line Previous line Next line Back to beginning of page Forward to end of page Back to beginning of text Forward to end of text
Shift-Left arrow Shift-Right arrow Option-Shift-Left arrow Option-Shift-Right arrow Command-Shift-Left arrow Command-Option-Shift-Left arrow Command-Shift-Right arrow Command-Option-Shift-Right arrow Shift-Up arrow Option-Shift-Up arrow Shift-Down arrow Option-Shift-Down arrow Command-Shift-Up arrow Command-Shift-Down arrow Command-Option-Shift-Up arrow Command-Option-Shift-Down arrow
Selecting Text
A-3
APPENDIX
Manipulating Selected Text

You can use the commands listed in Table A-3 to manipulate selected text. As the table shows, NTK supports the customary Macintosh commands for cutting (Command-X), copying (Command-C), and pasting (Command-V).
Table A-3 Manipulation
Manipulating selected text Kaystrokes
Indent selection left Indent selection right Transpose selection with one character forward Cut selection to Clipboard Copy selection to Clipboard Paste contents of Clipboard over selection
Command-[ Command-] Control-T Command-X Command-C Command-V
A-4
Manipulating Selected Text
APPENDIX
Deleting Text
You can delete text with the keyboard commands listed in Table A-4. The NTK keyboard editing commands do not place deleted text onto the Clipboard; to delete the selection and place it on the Clipboard, use Command-X.
Table A-4
Deleting text with keyboard commands Keystrokes
Scope of deletion
Selection only Selection or one character back Selection or one character forward Selection or one word back Selection or one word forward Selection and to end of line Selection and to end of text
Clear Shift-Clear Delete Shift-Delete Control-D Delete forward Shift-Delete forward Option-Delete Option-D Option-Delete forward Control-K Command-Delete Command-Option-Delete Command-Delete forward Command-Option-Delete forward
Deleting Text
A-5
APPENDIX
Changing the Meaning of the Next Keystroke

You can use the key combinations listed in Table A-5 to modify the interpretation applied to the next keystroke.
Table A-5 Kaystrokes
Changing the interpretation of the next keystroke Effect
Control-[ Escape Control-U
Interpret next keystroke as Option-keystroke Multiply next keystroke by four The sequence Control-U Option-B, for example, moves the insertion point back four words
Control-Q
Quote next characterthat is, ignore any special meaning and insert character code into text The sequence Control-Q Option-B, for example, inserts an integral sign; Option-B alone moves the insertion point back one word
A-6
Changing the Meaning of the Next Keystroke
APPENDIX
Keyboard Shortcuts
This appendix lists keystroke combinations that invoke NTK menu items and that affect views in a layout or Browser window. The Command key on a Macintosh keyboard is the key with the propeller symbol and, possibly, an open Apple symbol.
Table B-1
Keyboard equivalents to menu items Effect
Key combination
Command-N Command-T Command-O Command-W Command-S Command-M Command-P Command-Q Command-Z Command-X Command-C Command-V Command-D Command-A
New Layout New Proto Template Open Close Save Save All Print Quit Undo Cut Copy Paste Duplicate Select All
continued
B-1
APPENDIX
Keyboard Shortcuts
Table B-1
Keyboard equivalents to menu items (continued) Effect
Key combination
Command-L Command-F Command-G Command-1 Command-2 Option-Down arrow Option-Up arrow Command-Y Command-I Command-= Command-E Option-Down arrow Option-Up arrow Command-K Command-B
List Find Find Next Build Package Download Package Move Forward Move Backward Preview Template Info New Slot Apply Move Forward Move Backward Connect Inspector New Browser
The keyboard commands listed in Table B-1 move templates within the view hierarchy. You can issue these commands with a template selected in a browser window. When a view is selected in a layout window, the Option key in combination with the arrow keys resizes the view, as described in Resizing a View beginning on page 4-16.
B-2
APPENDIX
Keyboard Shortcuts
Table B-2
Keyboard commands that affect the hierarchy
Key combination
Effect
Option-Left arrow Option-Right arrow Option-Up arrow Option-Down arrow
Move the template one layer up in the hierarchy Move the template one layer down in the hierarchy Move the template one place up in the drawing list (that is, move view backward) Move the template one place down in the drawing list (that is, move view forward)
B-3
APPENDIX
Using Resources
A resource is a piece of data stored on the development system and incorporated into a Newton application during the project build. You can use resources to bring data from other sources into your application. NTK explicitly supports 'PICT' resources and 'SND ' resources, and it includes functions for retrieving any other resources your application can handle. This appendix describes how to embed 'PICT' and sound resources in Newton applications and how to retrieve your own resources.
About Resources
A resource is a collection of data with a dened structure, stored in a designated resource le. Each resource has a typean identier specifying the format used to store the dataand a resource number thats unique within resources of the same type. The Macintosh environment provides predened resource types for commonly used data formats such as pictures, sounds, and fonts. NTK recognizes these resource types and provides functions that let you make use of Macintosh-style resource data in your Newton application. The functions described in this appendixfor opening and closing resource les and retrieving resources from themare available on the Macintosh during the build. Theyre not available on the Newton at run time. Therefore, you can manipulate resources only in code thats executed during the build.
About Resources
C-1
APPENDIX
Using Resources
Resource Files
Resource data itself can come from a number of sourcesit may be the output from a utility program that captures sound or picture data and stores it in a le; it can be described textually and then compiled in a Macintosh application development environment such as the Macintosh Programmers Workshop (MPW); or it can be copied, cut, pasted, and otherwise manipulated with a resource-editing program like ResEdit. (ResEdit and MPW are available from APDA.) Compiled resource data ultimately resides in a le known as a resource le. Macintosh resource les in NTK are customarily identied by a .rsrc lename extension. A single resource le can contain multiple resources of dissimilar types.
Adding Resource Files to a Project

To include a resource le in a project, list it in the project le through the Add File item in the File menu.
Using Resources
You can include 'PICT' resources in an application by inserting them into any picture slot. To retrieve other resources, you must 1. open the resource le 2. extract the resource data 3. embed the resource data into the application 4. close the resource le. You must retrieve resources in code that executes only on the Macintosh typically in your project data le.
C-2
About Resources
APPENDIX
Using Resources
Opening and Closing Resource Files

NTK automatically opens and closes the resource les containing 'PICT' resources that you acess through the picture slot editor or the Project Settings dialog box. You need to open and close resource les only if youre manipulating the resources directlywhen youre using sound resources, for example, or when youre using resources specic to your application. Manipulating Single Resource Files To open and close resource les one at a time, use the OpenResFile and CloseResFile functions. OpenResFile accepts as its argument the pathname to the resource le to be opened; this function closes the currently open resource le and opens the one specied by its argument. CloseResFile accepts no arguments; it expects only one resource file to be open when its called. This example illustrates opening and closing two resource les sequentially. // open first rsrc file; note use of HOME variable OpenResFile(HOME&"My1stResourceFile.rsrc"); // do things with My1stResourceFile while its open . . . // next call to OpenResFile closes My1stResourceFile.rsrc OpenResFile ("HD:Folder:MyNextResourceFile.rsrc"); // do things with MyNextResourceFile while its open . . . // close .rsrc files before exiting Project Data CloseResFile(); Manipulating Multiple Resource Files If you need to open multiple resource les to compile your application, youll need to use the OpenResFileX and CloseResFileX functions, rather than their single-le counterparts. The OpenResFileX function accepts as its argument the pathname to the resource le to be opened but does not close any resource les that are
About Resources
C-3
APPENDIX
Using Resources
currently open. This function returns a reference to the resource le that it opens; you later pass the reference to the CloseResFileX function to specify which resource le to close. This example shows how to open and later close two resource les at once. // save the refnum -- youll need it to close the file refNum1 := OpenResFileX(HOME&"Happy.rsrc"); refNum2:= OpenResFileX("HD:Folder:Joy.rsrc"); . . . // do things with resources while files are open // close resource files before exiting Project Data CloseResFileX(refNum1); CloseResFileX(refNum2);
Extracting Resource Data

Once the resource le is opened, youll need to extract the resource data itself. You can use the functions GetResource and GetNamedResource to retrieve from an open resource le any resources that your code can handle. Because a resource le can contain multiple resources of any type, NTK provides functions for extracting resources in various ways. For example, you can specify the resources to be retrieved by name or by resource ID. Each Macintosh resource is identied by a number that is unique within its resource type; this number is called its resource ID and is assigned when the resource is created. The GetResource function retrieves from the open resource le the resource having the specied type and ID number. The resource is returned as a binary object having the class symbol specied by the nal argument to this function. This example uses GetResource to retrieve a resource. OpenResFile(HOME&"Happy.rsrc"); myPict:= GetResource('PICT', 1001, 'picture) CloseResFile();
C-4
About Resources
APPENDIX
Using Resources
This code returns resource number 1001 of type 'PICT' as a binary object of class 'picture; the binary object returned is assigned to the compile-time variable myPict. Each resource has a resource ID; you can also assign a name string to a resource. This name string can be used in conjunction with a resource type to specify the resource that the GetNamedResource function is to retrieve from an open resource le. Like GetResource, the GetNamedResource function also accepts an argument specifying the class that the returned binary object is to have. This example illustrates the GetNamedResource function. gCheckerBoard := GetNamedResource('PAT ', "checkerBoard", 'pattern); This line returns the resource named checkerBoard of type 'PAT ' as a binary object of class 'pattern; the binary object returned is assigned to the compile-time variable gCheckerBoard. Specialized Resource Extraction Functions The resource-extraction funcions described here do not interpret or process the binary resource data and therefore work with resources of all types. NTK also provides several specialized resource extraction functions that interpret or process the retrieved resource data in some way; these functions are described later in this appendix, in the sections Using 'PICT' Resources and Using External Sound Resources. Extracting Raw Binary Data You can also use various data-extraction functions to return raw binary data from a custom resource of your own design. For more information on these data-extraction functions, see the section Data Extraction Functions in the Utility Functions chapter of the Newton Programmers Guide.
About Resources
C-5
APPENDIX
Using Resources
Dening custom resources is not discussed in this book; for detailed information about creating Macintosh-style resources, see
n n
the Resource Manager chapter of Inside Macintosh: Overview the Resource Manager chapter of Inside Macintosh: More Macintosh Toolbox the chapter The Resource Compiler and Decompiler in MPW: The Macintosh Programmers Workshop Development Environment. the documentation that accompanies ResEdit.
Using the Resource-Handling Functions

Current versions of NTK and the Newton object system support some kinds of resources more fully than others. As the Newton object system and NTK continue to evolve, the use of external resources of all types will be more tightly integrated with the object system, with corresponding support being added to NTK. The use of 'PICT' resources is well supported in the Newton object system and NTK. For many of the system-supplied view prototypes, NTK locates the appropriate resource automatically when an external resource le is included in the applications NTK project le. On the other hand, the object system does not currently supply any prototypes that use external sound resource les; thus, you need to do a little more work to incorporate them in your application. This section describes how NTK handles 'PICT' and sound resources and describes data extraction functions that are specialized for these resource types.The information in this appendix is based on version 1.05 of the Newton ROM and version 1.0 of Newton Toolkit.
C-6
APPENDIX
Using Resources
Using 'PICT' Resources

You can draw your pictures in any graphics program, and then paste them as 'PICT' resources into a resource file in ResEdit. You add the resource file to an NTK project through the Add File item in the Project menu. NTK lets you add named'PICT' resources to picture slots in your templates through the standard picture slot editor, illustrated in Figure C-1
Figure C-1
Adding a named 'PICT' resource to a picture slot
The File pop-up menu contains all resources les that have been added to the project le. The Picture list shows all named 'PICT' resources in the selected le. For more information on the picture slot editor, see Editing Slots beginning on page 4-30.
Making a Bitmap From a 'PICT' Resource

NTK also supplies the GetPictAsBits function for extracting bitmaps from 'PICT' resources. NTK uses this function when manipulating the resources you access through the picture slot editor. The GetPICTAsBits function retrieves a 'PICT' resource by name from an open resource le, converts the 'PICT' to a bitmap, and returns a frame containing a bitmap object. It accepts as its arguments the name of the 'PICT' resource to be retrieved and a Boolean value specifying whether to
C-7
APPENDIX
Using Resources
retrieve the mask for the bitmap from the resource. This function is described completely in the Resource Functions section of this Appendix. The following code example retrieves the 'PICT' resource named Daphne and stores it in the compile-time variable gDaphBits.Note that the mask is not used. To make the bitmap available to the application, you would use the compile-time global gDaphBits to initialize an evaluate slot in the applications base view. OpenResFile(HOME&"MyPicts.rsrc"); gDaphBits := GetPictAsBits("Daphne", nil); CloseResFile(); You can make the bitmap data available by storing it in an evaluate slot in your applications base view. The Drawing chapter in the Newton Programmers Guide illustrates how you can use bitmap data when drawing.
Using External Sound Resources

You can use any program that saves 'SND ' resources to create sounds for your application. Some Macintosh models have a built-in sound-sampling program. NTK supplies the two functions, GetSound and GetSound11, for extracting sound data from these resources. The GetSound function reads a sound sampled at 22kHz and returns a Newton sound frame; the GetSound11 function reads a sound sampled at 22kHz, down-samples and lters it to produce data simulating the same sound sampled at 11kHz, and returns a Newton sound frame. The GetSound11 function reduces the space required to store sound data, at the expense of some of the resolution offered by a comparable 22kHz sample. Both functions expect the resource le containing the sound resource to be open already, and both functions accept as their sole argument a string specifying the name of the sound resource. The following code example retrieves by name the 'SND ' resource chickadee and stores it in the compile-time variable gChickadee.To
C-8
APPENDIX
Using Resources
make the sound data available to the application, you would create a compile-time global gChickadee to initialize an evaluate slot in the applications base view. OpenResFile(HOME&"MySounds.rsrc"); gChickadee := GetSound("chickadee"); CloseResFile(); See the Working With Sound chapter in theNewton Programmers Guide for more complete information on using sound in Newton applications.
Resource Functions
This section describes the functions used to make frame objects from resource data.These function are available only during compile timethey are not available at run time.

This section describes the functions you use for opening and closing resource les. OpenResFile OpenResFile(pathToFile) Opens the specied resource le. pathToFile A full or partial pathname to the resource le to be opened. The HOME variable may be used in this pathname. Pathnames that contain spaces must be enclosed in double quotation marks.
This function opens only one resource le at a time. If another resource le is open, OpenResFile closes it before opening the le specied by the value of the pathToFile parameter.
Resource Functions
C-9
APPENDIX
Using Resources
Note
To open multiple resource les at one time, use the OpenResFileX function. u OpenResFileX OpenResFileX(pathToFile) Opens the specied resource le and returns a reference to the open le. The reference that this function returns is typically saved in a local variable and passed as the argument to the CloseResFileX function. pathToFile A full or partial pathname to the resource le to be opened. The HOME variable may be used in this pathname. Pathnames that contain spaces must be enclosed in double quotation marks.
CloseResFile CloseResFile() Closes the currently open resource le. CloseResFileX CloseResFileX(fileRef) Closes the specied resource le. leRef A reference to the le to be closed; this reference is returned by the OpenResFileX function and must be saved for use with CloseResFileX.
Retrieving Resources
This section documents the functions to use to retrieve resources from an open resource le. You can retrieve resources by type and either name or resource ID.
C-10
Resource Functions
APPENDIX
Using Resources
GetNamedResource GetNamedResource(typeString, nameString, class) Retrieves from an open resource le the resource specied by nameString and typeString and returns the resource data as a frame having the specied class symbol. typeString nameString class A four-character string specifying the resource type of the data to be retrieved A string specifying the name of the resource to be retrieved. The symbol to be stored in the class slot of the frame returned by this function
GetResource GetResource(typeString, id, class) Retrieves the specied resource from an open resource le and returns the resource data as a frame having the specied class symbol. typeString id class A four-character string specifying the resource type of the data to be retrieved A numeric string specifying the resource ID of the data to be retrieved The symbol to be stored in the class slot of the frame returned by this function
GetSound GetSound(nameString) Retrieves the specied 22KHz sound resource from the currently open resource le and returns a Newton sound frame. nameString A string specifying the name of the sound resource to be retrieved. The sound must have been sampled at 22kHz.
Resource Functions
C-11
APPENDIX
Using Resources
If the specied sound is not sampled at that rate, NTK reports a compiler error: //-- Compiler Error:Sound resource:"Boing" must be sampled at 22 KHz To retrieve a sound samples at 11 Hz, use the GetSound11 function. The sound frame that this function returns has the following slots. sndFrameType The format of this sound frame. Currently, Newton sound frames always have the symbol 'simpleSound in this slot; future Newton devices may store other values here. A frame of class 'samples containing the binary sound data. The sound data must have been sampled at 11Khz or 22KHz. A oating-point value specifying the rate at which the sample data is to be played back A code that reects the data type. Currently, the value of this slot is always 1, indicating 8-bit samples.
samples
samplingRate dataType
compressionType A code that reects the compression strategy. Currently, the value of this slot is always 0 (zero), indicating no compression. GetSound11 GetSound11(nameString) Retrieves the specied 11KHz sound resource from the currently open resource le and returns a Newton sound frame. nameString A string specifying the name of the sound resource to be retrieved. The sound must have been sampled at 11KHz. If the specied sound is sampled at 22 Khz, NTK down-samples the sound (with ltering) from 22 Khz to 11 Khz, and returns a Newton sound frame that packages this sound as an 11kHz sample.
C-12
Resource Functions
APPENDIX
Using Resources
The sound frame that this function returns has the following slots. sndFrameType Species the format of this sound frame. Currently, Newton sound frames always have the symbol 'simpleSound in this slot; future Newton devices may store other values here. A frame of class 'samples containing the binary sound data. The sound data must have been sampled at 11Khz or 22KHz. A oating-point value specifying the rate at which the sample data is to be played back Currently, the value of this slot is always 1, indicating 8-bit samples. Currently, the value of this slot is always 0 (zero), indicating no compression. GetPictAsBits GetPictAsBits(nameString, maskToo) Retrieves the specied 'PICT' resource by name from an open resource le, converts the 'PICT' to a bitmap, and returns a frame containing a bitmap object and an optional mask. nameString maskToo A string specifying the name of the resource to be retrieved. A Boolean value indicating whether to construct a mask for the bitmap. If you specify true, GetPictAsBits constructs a mask for the bitmap and returns it with the bitmap. If you specify nil, GetPictAsBits searches for a mask, a 'PICT' resource in the same le with the resource name nameString!that is, the name of the primary resource with an exclamation point appended.
samples
samplingRate dataType compressionType
Resource Functions
C-13
APPENDIX
Using Resources
If the value of the maskToo parameter is nil but no such resource is found, GetPictAsBits returns only the primary resource. The bitmap object returned by this function is a frame with the following slots: bits bounds A reference to a binary object containing the bitmap data A bounds frame specifying the dimensions of the bitmap; for example, {left: 0, top: 0, right: bitmapWidth, bottom: bitmapHeight} mask This slot is included only if a mask has been constructed or supplied. It contains a reference to a binary object containing the mask bitmap.
Note
'PICT' resources are stored much more compactly as binary 'PICT' objects (obtained with GetNamedResource) than as bitmap objects (obtained with GetPictAsBits). u
C-14
Resource Functions
APPENDIX
Using Resources
Summary of Resource-Manipulation Functions

This section categorizes the resource-manipulation functions by task.

OpenResFile(pathToFile) OpenResFileX(pathToFile) // for multiple files CloseResFile() CloseResFileX(fileRef)// for multiple files
Getting Resource Data

GetNamedResource(typeString, nameString, class) GetResource(typeString, id, class) GetSound(nameString) GetSound11(name ) GetPictAsBits(nameString, maskToo)
Summary of Resource-Manipulation Functions
C-15
APPENDIX

This appendix describes the specialized slot editors you use for editing the system-dened slots. The description of the viewBounds slot, which is a simple rectangle slot, species the meanings of the four integers under different justication settings.
Script Slots
You edit the slots containing system-dened messages with the basic NTK text editor described in Editing Text beginning on page 4-32. The system messages appear in the Specic and Methods pop-up menus in the browser and New Slot dialog boxes. When you add one of these slots, NTK places the skeletal structure of the method in the slot. If you add a viewStrokeScript slot, for example, NTK denes the initial slot contents as func(unit) begin end If a method takes no parameters or requires no special return value, NTK sets the initial contents to the simple function statement func() begin end For descriptions of the standard methods, see the chapter Handling System Messages in the Newton Programmers Guide.
Script Slots
D-1
CHAPTER
View Attributes
The view attributes slots contain various specications that the Newton uses to create, display, and manipulate views. Some of the slots contain a single value or string. The viewOriginX and viewOriginY slots, for example, each contain a number, which you edit through the number editor. The viewFont slot contains a single string that specifies a font name. You edit it and the other attribute slots containing text with the standard NTK text editor, described in Editing Text beginning on page 4-32. This section illustrates the specialized editors you use to use to edit the more complex view attributes slots. For detailed descriptions of the elds, see the chapter Views in the Newton Programmers Guide.
viewBounds
The viewBounds slot denes the bounds of a view. NTK automatically lls in the viewBounds values when you lay out a view in the graphical editor. The values in the four slots are relative to the parent or sibling view, and the exact meaning varies with different justication strategies, as dened in the viewJustify slot. Table D-1 summarizes the meanings of the Left and Right elds with different horizontal view justication settings. Table D-2 summarizes the meanings of the Top and Bottom elds with different vertical view justication settings.
D-2
View Attributes
APPENDIX
Table D-1 Justication
Meaning of viewBounds elds for horizontal justication
Meaning of Left
Meaning of Right
Left Relative
The offset from the parents or siblings left edge to the views left edge. The offset from the parents or siblings right edge to the views left edge. The left offset of the views center from the parents or siblings center. The offset of the views left edge from the parents or siblings left edge.
The offset from the parents or siblings left edge to the views right edge. The offset from the parents or siblings right edge to the views right edge. The total width of the view.
Right Relative
Center Relative
Full Relative
The offset of the views right edge from the parents or siblings right edge.
Table D-2 Justication
Meaning of viewBounds elds for vertical justication
Meaning of Top
Meaning of Bottom
Top Relative
The offset from the parents or siblings top edge to the views top edge. The offset from the parents or siblings bottom edge to the views to the views top edge The vertical offset of the views vertical center from the parents or siblings center. The offset of the views top edge from the parents or siblings top edge.
The offset from the parents or siblings top edge to the views bottom edge. The offset from the parents or siblings bottom edge to the views bottom edge. The total height of the view
Bottom Relative Center Relative
Full Relative
The offset of the views bottom edge from the parents or siblings bottom edge.
View Attributes
D-3
APPENDIX
viewFlags
viewFormat
viewJustify
D-4
View Attributes
APPENDIX
viewEffect
viewTransferMode
Specic Slots
The slots in the Specic pop-up menu represent the slots that are specic to the selected proto. These slots hold methods or simple values that you edit with one of the standard slot editors.
Specic Slots
D-5
Index
A
activation records 5-5 Add Book File command 4-2, 6-11 Add File command 4-2, 4-44, 6-11 Add Window command 4-2, 6-11 afterScript slots 4-50 Align command 6-18 Alignment command 4-18 to 4-19, 6-17 application base view 3-4, 4-12 Apply command 4-27, 6-21 AutoClose 4-5 Autogrid On command 6-15 Automatic download option 4-10 Automatic indent option 4-10 Automatic save option 4-10 build heap 4-11 Build Package command 4-47 to 4-50, 6-12 application build sequence 4-47 book build sequence 4-48 Preferences settings 4-6 processing templates 4-49 to 4-50 project settings 4-4
C
class slot 5-5 Clear command 6-6 Clone function 5-30 cloning 5-30 Close command 6-3 CloseResFile function C-10 CloseResFileX function C-10 codeBlock slot 5-5 compression 4-7 Connect Inspector command 4-52, 6-22 contextFrame slot 5-6 Copy command 6-6 copying read-only objects 5-30 copy protection, build option 4-7 copyright, package 4-7 Cut command 6-6
B
base view application 3-4 layout 3-15 beforeScript slots 4-49 books adding a book le to a project 4-2 build sequence 4-48 Boolean slots 4-31 BreakLoop function 5-3, 5-17 breakOnThrows variable 5-8, 5-15 browser 4-26 to 4-33 browsing templates 4-26 to 4-28 editing templates 4-28 to 4-33 Preferences settings 4-9 tutorial 3-9 to 3-12
D
debug build option 4-4 Debug function 5-13, 5-17
IN-1
INDEX
debugging 5-1 to 5-33 cycle with Inspector 5-2 examining the stack 5-5 to 5-8 functions for 5-16 to 5-22 trace 5-3 tracing execution ow 5-3 to 5-5 tutorial 3-26 to 3-30 variables for 5-15 to 5-16 debugging functions 5-16 to 5-22 debug slot 4-4, 5-13 declaring views 4-21 DefConst function 4-41 to 4-42 Delete Slot command 6-20 Display function 5-9, 5-18 displaying values 5-9 controlling the depth 5-10 Debug function 5-13 Display function 5-9 DV function 5-14 Print function 5-9 Write function 5-9 Download Package command 4-2, 6-12 automatic Preferences setting 4-10 Duplicate command 6-6 DV function 5-14, 5-18
F
les adding to project 4-2 layout 4-2, 4-22 print format 4-25 proto 4-24 resource 4-5 saving 4-10 Find command 4-35 to 4-36, 6-8 Find Inherited command 4-36, 6-9 Find Next command 4-35 to 4-36, 6-8 functions BreakLoop 5-3, 5-17 Clone 5-30 CloseResFile C-10 CloseResFileX C-10 Debug 5-13, 5-17 Defconst 4-41 Display 5-9, 5-18 DV 5-14, 5-18 ExitBreakLoop 5-8, 5-17, 5-19 GC 5-20 GetLocalFromStack 5-20 GetNamedResource C-11 GetPictAsBits C-13 GetResource C-11 GetSound C-11 GetSound11 C-12 HasSlot 5-30 OpenResFile C-9 OpenResFileX C-10 Print 5-9, 5-21 StackTrace 5-5, 5-21 Stats 5-22 Write 5-9, 5-22
E
error messages 4-50 evaluate slots 4-30 exceptions breaking for 5-8 ExitBreakLoop function 5-8, 5-17, 5-19 Export Package to Text command 6-12
IN-2
INDEX
G
GC function 5-20 GetLocalFromStack function 5-20 GetNamedResource function C-11 example C-5 GetPictAsBits function C-13 GetResource function C-11 example C-4 GetSound11 function C-12 GetSound function C-11 global data le 4-38 Grid on setting 4-8
K
keyboard text-editing commands A-1 to A-6
L
lastExError variable 5-32 lastExMessage variable 5-32 lastEx variable 5-32 layout_lename constant 4-42, 4-49 layout base view 3-15 layout les constants and variables referencing 4-42 to 4-43 creating 3-4, 4-11 dened 2-3, 4-12 linking 3-17 to 3-19, 4-22 to 4-24 layout Preferences settings 4-8 Layout Size command 6-15 layout size setting 4-9 layout view 4-12 linked subviews 3-14, 3-17, 4-23 to 4-24 dened 4-13 LinkedSubview template 4-23 Link Layout command 4-23, 6-2 List command 4-34 to 4-35, 6-7
H
hardware requirements 1-2 HasSlot function 5-30 heap sizes 4-11 HOME variable 4-42
I, J
icon, application 4-6 indenting 4-10 Inspector 4-51 to 4-52, 5-1 to 5-16 connecting 1-7, 5-2 tutorial 3-26 to 3-30 using 5-2 to 5-15 installation connecting a Newton to a Macintosh 1-5 installing NTK on a Macintosh 1-2 to 1-5 installing the Toolkit App on a Newton 1-6 troubleshooting 1-8 install scripts 4-40 Install Toolkit App command 1-6, 6-13 instantiation 2-2
M
main heap 4-11 Mark as Main Layout command 6-13 masks 4-32 Move Backward command 4-19, 6-17 Move Forward command 4-19, 6-16 Move To Back command 4-20, 6-16 Move To Front command 4-20, 6-16
IN-3
INDEX
N
name application 4-4 package 4-7 naming views 4-21 New Browser command 4-26, 6-22 New Layout command 4-11 to 4-13, 6-1 New Print Format command 4-25, 6-2 New Project command 4-2, 6-11 New Proto Template command 4-24, 6-2 New Slot command 4-28 to 4-29, 6-19 Newt Screen Shot command 6-9 number slots 4-31
O
object values, displaying 5-9 Open command 6-2 Open Inspector command 4-52, 5-1, 5-2, 6-22 Open Project command 6-11 OpenResFile function C-9 example C-3 OpenResFileX function C-10 example C-4
P
packages 4-37 copy protecting 4-7 dened 2-3 downloading 4-10 version number 4-7 Page Setup command 6-4 Paste command 6-6 'PICT' resources C-7 to C-8 in application icon 4-6 in picture slots 4-31 to 4-32
picture slots 4-32 platform les 4-43 specifying 4-6 platform project setting 4-6 Preferences settings 4-7 to 4-11 Preview command 4-20, 6-18 preview mode 4-20 Print command 6-5 printDepth variable 5-10, 5-16 printFormat_lename variable 4-43 print format templates 4-25, 4-47 Print function 5-9, 5-21 Print One command 6-5 programming problems 5-23 to 5-33 comparing with nil 5-26 to 5-28 dangling frame references 5-26 forgetting the function value 5-25 printing in communications code 5-31 resizing read-only objects 5-29 to 5-30 setting the wrong slot value 5-23 to 5-25 text not drawing 5-30 using nil in expressions 5-28 to 5-29 programming tips 5-23 to 5-33 accessing parent view 5-33 examining exceptions 5-32 maintaining view state 5-32 peeking into a soup 5-33 Project Data command 6-13 project data les 4-39 to 4-42 project les 4-2 projects adding les 3-7, 4-2 dened 2-3 managing 4-1 to 4-7 project settings 4-3 to 4-7 project windows 4-2 setting up 3-2 protos 4-13
IN-4
INDEX
Q
Quit command 6-5
R
read-only objects copying 5-30 receiver slot 5-6 rectangle slots 4-32 Remove File command 6-11 remove scripts 4-40 to 4-41 Rename Slot command 6-20 resource les C-2 adding to a project 4-44, C-2 for application icon 4-5 opening and closing C-3 to C-4, C-9 to C-10 resources 4-44 to 4-45, C-1 to C-15 application icon 4-5 to 4-6 'PICT' 4-6, 4-32, C-7 to C-8 retrieving C-4 to C-6, C-10 to C-14 'SND ' C-8 to C-9 Revert command 6-4, 6-21
Show Slot Values command 6-21 Size setting 4-9 slots creating 4-28 to 4-32 displaying in browser 4-9 editing 4-30 to 4-33 in stack trace 5-5 searching for 4-34 to 4-36 slot types 4-30 to 4-32 Slots By Name command 6-21 Slots By Type command 6-21 'SND ' resources C-8 to C-9 software requirements 1-2 stack trace 5-5 StackTrace function 5-5, 5-21 Stats function 5-22 symbols, application 4-4 to 4-5
T
tabs, setting 4-10 Template Info 3-7, 4-21 Template Info command 4-21 to 4-22, 6-18 templates dened 2-1 displaying in browser 4-9 editing 3-9 to 3-12, 4-26 to 4-33 processing 4-49 to 4-50 searching for 4-34 to 4-36 Templates By Hierarchy command 6-21 Templates By Type command 6-20 text editing 4-32 to 4-33, A-1 to A-6 searching for 4-34 to 4-36 setting display characteristics 4-10 setting tabs 4-10 text slots 4-30 Toolkit App, installing 1-6 Toolkit Preferences command 4-7 to 4-11, 6-9 Trace Off button 5-5
S
Save a Copy In command 6-4 Save All command 6-4 Save As command 6-3 Save command 6-3 script slots 4-30 Select All command 6-6 Select Hierarchy command 6-7 Select in Layout command 6-7 Set Grid command 6-15 Settings 4-3 to 4-7 Settings command 4-3 to 4-7, 6-13 Show Clipboard command 6-9
IN-5
INDEX
trace variable 5-15 tracing execution ow 5-3 to 5-5 stopping 5-5 troubleshooting 1-8
W, X, Y, Z
Write function 5-9, 5-22
U
Undo command 6-5 Update File command 6-12 user proto templates creating 4-24 example 3-21 to 3-24
V
variables dened by NTK 4-42 to 4-43 version number, package 4-7 viewBounds slot elds D-2 view classes 4-13 view frames 2-2 viewFrontKey 5-19 viewFrontMost 5-19 viewFrontMostApp 5-19 views aligning 4-18 to 4-19 declaring 4-21 dened 2-1 displaying contents 5-13 displaying hierarchy 5-14 displaying in browser 4-9 drawing 3-5 to 3-6, 4-13 to 4-16 moving 4-17 naming 3-6, 4-21 ordering 4-19 previewing 4-20 resizing 4-16
IN-6
THE
APPLE
PUBLISHING
SYSTEM
This Apple manual was written, edited, and composed on a desktop publishing system using Apple Macintosh computers and FrameMaker software. Proof pages were created on an Apple LaserWriter Pro 630 printer. Final page negatives were output directly from the text and graphics les. Line art was created using Adobe Illustrator. PostScript, the page-description language for the LaserWriter, was developed by Adobe Systems Incorporated. Text type is Palatino and display type is Helvetica. Bullets are ITC Zapf Dingbats. Some elements, such as program listings, are set in Apple Courier.
LEAD WRITER
Sue Luttner
WRITERS
Gary Hillerson, Sue Luttner, John Perry

PROJECT LEADER
Christopher Bey
ILLUSTRATOR
Peggy Kunz
EDITOR
David Schneider
PRODUCTION EDITOR
Rex Wolf
PROJECT MANAGER
Gerry Kane Special thanks to Larry Breed, Bob Ebert, Mike Engber, Norberto Menendez, Jeff Piazza, Peter Potrebic, Kent Sandvik.

Newton Toolkit User's Guide

Uploaded by

Copyright:

Available Formats

Newton Toolkit User's Guide

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Newton Toolkit User's Guide

Uploaded by

Copyright:

Available Formats

What are the copyright restrictions mentioned in the document?

What are the copyright restrictions mentioned in the document?

What are the different types of resources mentioned?

What are the different types of resources mentioned?

Newton Toolkit Users Guide

About This Book

Installation and Setup

Programming With theNewton Toolkit

A Quick Tour of NTK

Using the Newton Toolkit

4-47 4-49 4-51

Keyboard Text-Editing Commands

Specialized Slot Editors

Figures and Tables

Installation and Setup

Hardware and software requirements

Programming With theNewton Toolkit

The Newton application development process

A Quick Tour of NTK

Layout window and palette A browser window 3-11

Using the Newton Toolkit

5-1 Debugging variables 5-15 Exception handling global variables

Keyboard Text-Editing Commands

Adding a named 'PICT' resource to a picture slot C-7

Specialized Slot Editors

About This Book

How to Use This Book

Developer Products and Support

Fax AppleLink America Online CompuServe Internet

Installation and Setup

Installation and Setup

Hardware and software requirements

Macintosh Model Available RAM Operating System System Settings

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

Installing NTK on the Macintosh

Installing NTK on the Macintosh

Installation and Setup

3. Double-click the Installer icon to begin installation.

Installing NTK on the Macintosh

Installation and Setup

Installing NTK on the Macintosh

Installation and Setup

Installing the Toolkit App on the Newton

Making the Physical Connection

Installing the Toolkit App on the Newton

Installation and Setup

Downloading the Toolkit App

Installing the Toolkit App on the Newton

Installation and Setup

Making an Inspector Connection

Making an Inspector Connection

Installation and Setup

Programming With the Newton Toolkit

Terms and Concepts

Terms and Concepts

Programming With the Newton Toolkit

Terms and Concepts

Programming With the Newton Toolkit

The NTK Development Process