Use/Create Newton Waba Applications!

Some external links may be obsolete -- if you have updates, please send.

Last updated: 25-Jun-2005

• What is Waba?
• Some Terminology
• Use Waba apps on...
  • the Web
  • Palm/WinCE
  • the Newton
• Create Waba apps for...
  • the Web
  • Palm/WinCE
  • the Newton: using
    • Warp/Exegen/GUI (desktop/Java)
    • WabaTester (Newton)

What is Waba?

Waba is a subset of Java. Waba apps can be run in a web browser, but also on Palm, Windows CE (aka "WinCE") and -- now! -- on Newton if a WabaVM (virtual machine) is installed. Developers use standard Java language and tools to create Waba apps; however, Waba has a much smaller library of core objects than Java.

• www.wabaworkbench.com articles, tools
• Are you ready for Waba?

Some Terminology

Before delving into the "how tos", it would be useful first to define/summarize various file formats (extensions), tools and acronymms:

JDK

Java SDK -- Software Development Kit for creating Java applications

.java

Java source file; create/modify with a text editor or your favorite JDK

javac

a Java compiler that converts source text (.java) files into Java bytecode (.class) files; run it from a command line prompt, or your JDK

.class

Java compiled/object file

.class files can be extracted from .jar (using jar); or from .pdb/.wrp (using Java-based Warp)

(javap tool can be used to disassemble .class into a pseudo-source listing)

.bmp

Windows BitMaP file; .wbm is less common

B&W is most common/compatible resolution; some WabaVMs and OS support grayscale or color; NOS 2.1 gray support has not really been tested

by convention, icon.bmp is the application's icon (if any)

.bat, .sh

batch/shell file for use in a command-line environment (DOS,Unix)

of interest to power users, or those who can't run wababin.GUI tool

jar

tool to create a Java ARchive file that bundles (and optionally compresses) multiple .class (and other resource) files in a ZIP-compatible format; typically used for shared libraries and for applications delivered in a browser

.jar

archive file containing .class files (and .bmp images if any)

application .jar files should be uncompressed and include .bmp to allow the possibility of direct download via Newt's Cape and running via WabaTester as helperApp, though generally easier for end users to just download precompiled .pkg

library .jar files can be compressed (Newton uses the .pkg versions)

.htm

an HTML file can contain a Java applet that can be run locally or remotely in a web browser

it typically accesses application and library .jar files

JRE

Java Runtime Environment; the supporting libraries for Java applications and applets

MRJ

MacOS Runtime for Java: an older Macintosh JRE

JVM

Java Virtual Machine; finds and interprets .class files from app and libraries; used for regular Java applications, as well as Waba apps that run in a browser or on desktop

Waba VM

Waba Virtual Machine; a scaled-down JVM suitable for handheld devices, e.g., Palm, WinCE,

application/applet

an applet is a Java application with restrictions, e.g., its security policy prevents access outside its host directory (i.e., no access to local file system)

a typical Waba application will be referred to here as "MyWabaApp", and generically as "app"

appletviewer

tool for running applets (simpler/smaller than browser)

library

a Waba library will be referred to here as "mywabalib" and generically as "lib" or "library".

classes shared by one or more applications

Palm and WinCE

the standard waba library is bundled with the WabaVM; each application includes all other classes it needs (no sharing), though .class files in .jar are excluded

desktop (regular Java)

waba (and other libraries) are in .jar files or classes/ directories; each application (via in JDK and JRE) references via "classpath" (environment setting)

Newton

you need at least waba.pkg (distributed with WabaVM), and sometimes wextra.pkg

waba (and other libraries) are separately installed autoparts

an application can specify libraries: Warp excludes these classes from app; appRequires (analogous to classpath) specifies libraries to check at startup, and order of library lookup (if this is important). Library Notes

"warp" file (Waba Application Resource Package)

similar to a .jar, this is a platform-specific file that contains .class (and .bmp) resources

"exegen" file

similar to a .htm, there is usually a second (executable) associated file that launches the Waba VM with the warp file, the main class name, and various initialization parameters; it may include an application icon.

Warp

tool for creating warp files

examples: .pdb, .wrp, .pkg~, .cls.txt

the Java-based version includes Newton support, and ability to extract .class and .bmp files from .pdb and .wrp

Exegen

tool for generating the exegen (launcher/parameter) file

examples: .prc, .lnk, .pkg, .arg.txt

the Java-based version includes Newton support, and ability to extract parameters from .lnk, and parameters and icon.bmp from .prc

wababin.GUI

Java-based user interface that controls javac, jar, appletviewer, Warp, Exegen

.pdb

Palm "database" warp file

.prc

Palm "resource" (exegen) file

.wrp

WinCE warp file

.lnk

WinCE shortcut (exegen) file

NTK

Newton ToolKit; a Macintosh and Windows desktop tool for creating Newton applications

(no longer required for most desktop .pkg creation)

.cls.txt

warp information encoded in a text file to add to an NTK project

.arg.txt

exegen parameters and icon to add to an NTK project

.pkg~

an interim Newton package file that contains warp but not exegen information

(this temporary file can be deleted after final .pkg created with Exegen)

.pkg

a complete Newton package application file that combines both warp (content) and exegen (launcher) data. A Newton package can be created by Warp/Exegen/GUI (and NTK) or WabaTester/NewtPack

design note: like the other platforms, I had considered having two files, one autopart package with just the classes and bitmaps (which would be installed as a library), and the other a slimmed down application with icon and parameters, that just launched WabaVM. Having two would have taken up more space and added complexity, without providing any real benefits.

to distribute a Newton package for Macintosh users, you can fix the creator/type via PackType (or tell users)

WabaTester

a Newton-based tool for inspecting and running files in any of these formats, and saving a Newton .pkg using NewtPack plugin

Newt's Cape

a Newton-based browser (among other things); version 2.1e (and later) processes the APPLET tag, downloads the .jar for any Waba app, passes it to a helperApp (WabaTester), which then runs the app (assuming the .jar is uncompressed and contains all necessary classes and images). (Easier, of course, to just download a pre-compiled .pkg).

Use Waba apps on the Web

Requirements

environment and viewer

JRE; Java-capable browser or appletviewer

libraries

waba.jar (and any other required libraries) in local or server directory

.htm file

with ARCHIVE attribute that references libraries, and PARAM tag with appClass attribute that references mainClassName (example)

application classes and images (if any)

directory that contains .htm, .jar; images (.bmp) in .jar or directory

Process

1. browse/open MyWabaApp.htm file
2. use and enjoy MyWabaApp

Examples

• Steve's Waba Apps

Use Waba apps on Palm/WinCE

Use Waba apps on the Newton

Requirements

2.x Newton MessagePad/eMate

MP2100 or MP2000 recommended

installed preferably on Internal store

libraries

lib_pkg/waba.pkg: core classes (see WabaVM distribution), installed preferably on Internal store; it contains WabaVM classes (these are different versions from those from WabaSDK used for web): waba/fx/*, waba/io/*, waba/lang/*, waba/sys/*, waba/ui/*, waba/util/*

other required libraries, e.g., wextra.pkg

the application

standalone Newton package (MyWabaApp.pkg) -- many are available in .pkg format in the app_pkg folder

(if not available as .pkg, you need the application files in another format, and creation/transfer tools)

Process

1. install required Newton packages (above)
2. open MyWabaApp(.pkg) from Extras; possibly adjust memory parameters
3. use and enjoy MyWabaApp
4. close MyWabaApp via its close box, or by toggling its icon in Extras

Create Waba apps for the Web

As indicated in Use Waba apps on the Web, you can access Waba applications via a web page. For example,

Scribble.htm:

<HTML><HEAD><TITLE>Waba: Scribble</TITLE></HEAD>
<BODY><HR><applet code="waba/applet/Applet.class"
	archive="Scribble.jar,waba.jar" width="160" height="160">
<param name="appClass" value="Scribble">
</applet><HR></BODY></HTML>

This is a little different from regular Java Applets. The appClass parameter is the name of the (real) main class of the application, usually contained in the first file in the archive attribute list.

Process

1. compile .java source files
2. archive .class (and .bmp) files in .jar
3. create MyWabaApp.htm (see example above) -- you can use GUI HTML command
4. store MyWabaApp.htm, MyWabaApp.jar, waba.jar (and other libs) in your directory
5. test using browser or appletviewer

Create Waba apps for Palm/WinCE

Create Waba apps for Newton

There are two complete approaches for creating Waba applications for the Newton:

WabaTester for Newton

Historically, WabaTester arose first since I was more familiar with NewtonScript than Java, and WabaTester could interact much more directly with the WabaVM, without having to create a Newton package. WabaTester is more suited for inspecting or retargeting existing/finished applications; it could provide a complete environment if someone wanted to create/port a small Java compiler to the Newton! WabaTester may appeal to those who like to do most things on their Newtons, though it is somewhat cumbersome to transfer files to the Newton, and packages back to the desktop.

Warp/Exegen/GUI for Java

More recently, I adapted the Warp/Exegen tools (specifically the Java-based versions distributed with the wextra library) to output a format for NTK (.cls.txt and .arg.txt); a NTK template used code from WabaTester for .bmp conversion; NTK generated the .pkg; WabaTester was still used to test/retarget applications available only in Palm and WinCE formats (i.e., extract .class and .bmp files). Finally, I added these 3 features to Warp/Exegen: .bmp conversion, .pkg generation, .class/.bmp extraction, and added a user interface to assist in the entire process: compiling and testing app, creating jar, testing applet, running Warp and Exegen. So, assuming you have a Java JDK:

• Warp/Exegen now provides a complete solution for Waba application generation
• GUI control panel should eliminate ordinary use of command lines
• WabaTester should not be necessary (though it will continue to be available)
• NTK should not be necessary (though it's still possible to obtain .cls.txt and .arg.txt from Warp/Exegen and WabaTester; and it is still used for the waba library and to create the app/lib .pkg templates used by Warp)

Create Waba apps for Newton on desktop/Java

This section discusses a recommended process for creating Newton apps in Java (typically on the desktop) using "GUI" interface to control various tools, particularly Warp/Exegen; it also mentions alternatives using command lines and variations involving NTK.

Requirements

JDK 1.2 (or greater), e.g., Java

to compile .class files for your app, and to run Warp/Exegen/GUI tools and your apps

JDK 1.3 recommended for full functionality; with JDK 1.2, wababin.GUI should mostly work, though you will be limited to executing commands in the same (application) directory where it launched

tested JDK configurations -- your mileage may vary; I'm interested in hearing about successes(problems) with other tools/configurations, and will update this accordingly:

Windows 2000, Sun JDK 1.3 [Steve]

Warp/Exegen/GUI developed/tested in this, many apps generated

see tutorial "Waba apps for Newton with Windows" [Victor] URL??

Mac OS X, 10.0.2. Sun JDK 1.3 [Sean]

Warp/Exegen work from command line; GUI fails?

see tutorial "Building Newton Waba Apps on MacOS X" [Sean] URL??

Mac, MRJ MPW tool [Paul]

MacOS 9.1, MRJ 2.2.4, MRJ SDK 2.2 [Steve]

GUI basically useless due to old JDK (~1.1.8) support and pseudo-command-line environment, though Warp and Exegen run via JBindery (MRJ Notes)

other tutorials, configurations??

tell me successes/hints...

wababin.jar (or classes/wababin/...)

GUI, Warp, Exegen and related .class files (latest versions)

(optional) wababin_cmds

various command-line (.bat) files

(you can use GUI in help-mode to see constructed command line with current parameters)

application source

MyWabaApp as .java or .class files, and any images as .bmp files; for an existing app, these could be extracted from a .jar file, or .pdb/.prc or .wrp/.lnk files

libraries

waba.jar (or ...wabasdk.10/classes) in your classpath

other libraries, e.g., wextra.jar

for .pkg creation, apptemplate__.pkg, libtemplate__.pkg (check that these are part of wababin/pkg)

(optional/deprecated) Newton ToolKit for Macintosh or Windows

NTK, NTK and app_templates to build Newton packages from .cls.txt and .arg.txt files (NTK Notes)

GUI Simulation

You can run the latest version of GUI as an applet, and use just "help" mode; however, the following is reasonably recent/accurate HTML/JavaScript simulation of the current interface with default values; this too supports only "help" -- select items to see short descriptions:

Process

This lists several environment and application configuration issues, then describes how to create applications (and libraries) using Warp/Exegen via GUI. Some command files are mentioned in [brackets]; if you turn on help-mode, you will see command-lines generated from current parameter settings. For text parameters, if you set the field to empty, the default value will be used.

path

(optional) set your PATH environment variable to make executable programs available -- varies depending on platform and your directory structure; usually this is configured when you install a JDK; this shouldn't be necessary unless you want to access older (non-Java WabaSDK) versions of warp/exegen and/or use wababin .bat command files

e.g.: set PATH=%PATH%;C:\waba\cmds

classpath

set your CLASSPATH environment to make Java .class and .jar files available to JDK and JRE, both for wababin tools and your apps -- varies depending on platform and your directory structure

Warp requires library (waba, wextra) files not in .jar; wababin classes can remain in .jar unless you are making changes

current recommendations:

appletviewer

copy waba.jar, wextra.jar to a directory, e.g., c:\waba\web

select that directory directly later if using HTML-appletviewer button

"classpath" is APPLET's ARCHIVE attribute

using GUI,Warp,Exegen

expand waba.jar and wextra.jar under a \classes directory

e.g.,set CLASSPATH=%CLASSPATH%;c:\waba\lib\wababin.jar;c:\waba\classes

modifying GUI,Warp,Exegen

expand wababin under \classes directory and change classpath

application source

collect your .java and .bmp files into a folder, e.g., MyWabaApp (mywabalib). your main class would typically be named MyWabaApp (library is directory root of a package, e.g., mylib); your application icon (if any) would be icon.bmp

to retarget (to desktop or Newton) an existing application that's available only in Palm or WinCE format, use extract to obtain .class and .bmp files

GUI

launch GUI

(for pre-1.3 JDK, connect first to application directory)

[jgui.bat]: java wababin.GUI

this assumes your classpath references wababin.jar or /classes directory containing wababin .class files

(optional) set different JDK tools

(not really tested; assumes tools use same command line args as Sun's tools; I wanted to call underlying classes directly, i.e., sun.tools.javac.Main, sun.tools.jar.Main, sun.applet.Main, but ran into classpath and security problems).

/c

compiler tool; default: javac

/j

jar tool; default: jar

/a

appletviewer tool; default: appletviewer

Main Class/Dir...

set application directory, and default appTitle (also used for filenames) and mainClassName

(lib) manually edit so that appName is name of package, with directory a level above that

for pre-1.3 JDK, connect to app directory before starting GUI (since you will not be able to change it)

(.bat) cd to app's directory, invoke the .bat file there

application mainClass

if this is not the same as the app's name, modify now (it's used by Run, HTML, Exegen)

if the mainClass is part of a package, use / to separate name parts (GUI will substitute . for / in commands if necessary)

the name is case sensitive

command: create, list, extract, help

create: Compile, Jar, HTML, Run*, Warp, Exegen

list: Jar, Warp

extract: Jar, Warp, Exegen; Warp creates .class and .bmp files (for Palm, WinCE); Exegen returns args, mainClassName, creator(for Palm), CEpath(for WinCE) -- best to choose one format at a time to see these updated values appear in GUI (compare against default values in labels); for NTK, extract does nothing; for .pkg, Warp does list (it would be easy to extract .class files, messier (and low priority) to convert Newton bitmaps to .bmp), Exegen will extract parameters and mainClassName from .pkg

note: since these commands can overwrite files in the selected directory, you should keep originals/backups elsewhere

help: status area shows short descriptions and generated commands based on current settings; for longer descriptions, enable verbose

verbose

displays more details during command execution in regular Java output/console window where you launched GUI)

Compile: this also enables -deprecation option

Warp, Exegen: verbose off same as /q (quiet)

Reset Defaults

return to original default settings

Compile

compile your Java source file(s)

[jwc.bat]: javac *.java

for .class files ~15% smaller (w/o debug info)

[jwcn.bat]: javac -g:none *.java

if you have a particularly complex directory structure, you might need to use the @ directive or a command file

Run App

test your app (.class) in a Java window

[jwr.bat]: java waba.applet.Applet MyWabaApp

note: you can set width, height parameters to check different app sizes

jar

create a .jar for testing within browser or for web distribution

[jwj.bat]: jar cvf *.class *.bmp

(optional) generally a .pkg is more convenient for most users, but WabaTester could use the .jar if it's uncompressed

[jwjn.bat]: jar cvf0M *.class *.bmp

HTML; appletviewer...

create a simple .htm file containing APPLET tag with title, mainClass and parameter attributes

when directory prompt appears, select a file in a target directory that contains waba.jar (and other libraries) -- GUI will copy .htm and .jar to that directory, then invoke appletviewer there. these several commands implement the web creation process outlined earlier

check/modify the ARCHIVE tag to include (or remove) libraries (default: wextra.jar,waba.jar)

Palm, WinCE, Newton(.pkg), Newton(NTK)

after your basic application is working in Java, you can generate it in a format for your favorite platform(s)

for Extract(Exegen), best to select a single format at a time if you want to see returned values in GUI

Warp

create/list/extract a "warp" file for app (lib), for one or more formats

[jwwn.bat]: java wababin.Warp c /q /f 15 MyWabaApp *.class

this generates MyWabaApp.pdb (for Palm), MyWabaApp.wrp (for WinCE), MyWabaApp.pkg~ (for Newton), MyWabaApp.cls.txt (mywabalib.cls.txt) (for NTK);

if there are .bmp files not referenced by main class, include these in command

"libraries"

for Newton formats, you can specify arbitrary parameters via the "create /c" field if the value begins with / -- in particular, you can specify up to 4 libraries, e.g., /l lib1 /l lib2 /l lib3 /l lib4

Exegen

create/list/extract "exegen" for app (lib), for one or more formats

check icon.bmp? setting and name of mainClass (esp. if it requires a path); eventually this might be a field that could allow a different .bmp filename (and possibly a secondw field for smaller Palm icon)

[jwwn.bat]: java wababin.Exegen /q /f 15 /i icon.bmp MyWabaApp MyWabaAppMain MyWabaApp

this generates MyWabaApp.prc (for Palm), MyWabaApp.lnk (for WinCE), MyWabaApp.pkg (for Newton), MyWabaApp.arg.txt (for NTK)

temporary Warp .pkg~ can be deleted manually

Library Notes

There are 3 situations where libraries are used:

1. during package creation [Warp]

Purpose: to eliminate common classes from an application (for size, upgradability). Classes in .jar are ignored anyway. Earlier, waba filtered for Palm,WinCE, waba and wextra for Newton. As of 6/01 (Newton only):

• a list of up to 4 library names can be specified, each preceded by /l
• waba is included implicitly; no need to include it explicitly unless order is important (a library overrides a built-in waba class).
• a library name corresponds to top of package(directory) path, e.g., mylib would omit any classes beginning with mylib/
• order of libraries is preserved in appRequires (to determine lookup order), important only if a library overrides a class defined in a later library

e.g.,  ... /l wextra /l mylib ...    (includes waba, wextra, mylib)
e.g.,  ...                           (no /l includes waba by default)

limitations:

• only 4 libraries are allowed (until apptemplate__.pkg is rebuilt)
• main library must be in a unique Java package (though overrides of library classes other than waba might be included also)
• "wextra" used to specify "extra" library (until extra and earlier apps are rebuilt)

2. upon application startup (application)

If waba or any library in appRequires is not installed, app notifies user and quits. This prevents an app from starting, but then failing later due to missing classes.

3. creating lookup context for classes (application)

Prior to 6/01, setAppContext (via method defined in the waba library), added only libraries specified in appRequires to the lookup context. Now, it always adds

• waba initially (unless explicitly listed in appRequires)
• any libraries in appRequires
• any other libraries that are installed

If appRequires is nil, it's ignored; if an entry in appRequires array is nil, it's ignored. So, appRequires is now used only to require classes at startup (#2) and to define lookup order, but not to limit which classes can be found.

This allows an application to omit library classes from an application in #1 by hiding them in .jar (rather than using /l), but still access them at runtime #3; however, there is no startup check (#2), so app may not encounter a missing class/library until later during execution.

Tool Integration Notes

This section briefly discusses issues related to calling other Java tools (javac, jar, appletviewer, Warp, Exegen) from "GUI". So far, I know of three techniques to invoke other tools from Java (I'd be interested in yet other alternatives, and for workarounds for these 3):

1. as application from OS

e.g., javac, using Runtime.exec (i.e., command line)

most general since it can be used with any (even non-Java) application. However, Runtime.exec may not be implemented correctly/consistently across platforms. e.g., the 3-arg version of .exec is available in JDK 1.3 (and later); even 1-arg version does not work correctly in Apple's MRJ (Apple Technical Note TN1168: The Care and Feeding of Runtime.exec)

2. as Java application from OS

e.g., java sun.tools.javac.Main, using Runtime.exec

same Runtime.exec drawbacks, plus possible configuration/security issues

3. as Java object from Java

e.g., javacObject.Main(...)

same config issues as #2, plus problem of tool .exit causing GUI process to exit also

Description of some of the issues:

configuration

#1: other tools usually default to GUI's classpath and security settings

#2, #3: classpath must be specified for "javac" but "appletviewer" still fails (so, app versions must be doing additional configuration)

directory

#1, #2: application directory can be changed via 3-arg .exec; setting "user.dir" system property directly can result in security violation

invoking the program

#1: as application (in new process) via Runtime.exec

#2: as class (in new process) via Runtime.exec

#3: as class (in same process) via Main method from GUI directly (using reflection)

monitoring

#1,#2: obtain output,error streams from process

#3: same streams as GUI

exiting

#1,#2: process termination does not affect GUI

#3: .exit terminates GUI also; (short of rewriting tool or gaining access via a different "Main" method, no way to override?)

MRJ Notes

My assumption is that most developers will have a "real" JDK available, but in case all you've got is Apple's MRJ, it is possible to use some of the tools. Here are my initial results of trying to use Warp, Exegen and GUI with Apple's MRJ 2.2.4, MRJ SDK 2.2 on MacOS 9.1 using JBindery:

GUI

opens, HTML button works; help (non-verbose) works (but you could just use the simulator here)

everything else does not work -- either I don't know how to configure, or MRJ calling command line (RunTime.exec) incomplete/buggy

javac

include waba.jar, wextra.jar in your classpath

(I don't know how to include folders like \classes)

Run App

use JBindery

class name: waba.applet.Applet

parameters: mainClassName, e.g., HelloWorld

classpath

1. your app folder, e.g., HelloWorld
2. waba.jar
3. wextra.jar (or wextra.jar and waba.jar could be accessed via classes folder)

Save Settings... (but uncheck Save as Application)

(once you've saved this, you can reuse for different apps -- just Edit app folder and mainClassName

Run

(output appears in console)

jar

I just use ZipIt, select files, Method Store

(entering file names manually for MRJ jar seems too painful)

HTML

this is the only thing (besides help) that works in GUI

appletviewer

open .htm file in AppletRunner (or browser)

Warp

use JBindery. like Run App, except:

class name: wababin.Warp

parameters: what you'd include on command line (use /f to select formats)

classpath

1. your app folder
2. classes/ (for waba, wextra)
3. wababin.jar (or via classes/)
4. MRJClasses

Exegen

use JBindery. like Warp, except

class name: wababin.Exegen

If someone really wants to try to get GUI working in MRJ (or other environments), look at the lines where .exec is called, possibly modifying the cmdVec array with other parameters.

NTK Notes

Most developers can ignore this section, but it is included since it might be preferred/needed by someone. Known situations where NTK might be needed to create a Newton package instead of Warp/Exegen:

• no Java available on your development system, just WabaTester on Newton
• unusual custom changes to an app (beyond changing icon, startup parameters, etc.) -- I don't have examples where this is needed
• waba library needs a setAppContext method and 3 additional java/lang entries which map to the corresponding waba/lang entries. Rather than include this method in every library, and the additional logic in Warp, this remains in NTK for now (I don't anticipate that this library needs to be updated often anyway).
• creating apptemplate__.pkg and libtemplate__.pkg for use by Warp (infrequent; plus probably done by Steve, since corresponding changes need to be made to Warp)

Process

1. obtain .cls.txt and .arg.txt files from Warp/Exegen or WabaTester
2. create an app (or lib) project in NTK: copy WabaNewApp.ntk (wabanewlib.ntk) into your MyWabaApp (mywabalib) folder
3. rename the project file: MyWabaApp.ntk (mywabalib.ntk); it already references WabaNewApp.lyt (wabanewlib.lyt) and WabaNewAppDefs.txt (wabanewlibdefs.txt) files, which you should not copy or change.
4. in NTK, Project/Open: MyWabaApp.ntk (mywabalib.ntk)
5. Project/AddFile: MyWabaApp.cls.txt (mywabalib.cls.txt) and MyWabaApp.arg.txt ()
6. fix build sequence; move (option-arrow) WabaNewApp.lyt (wabanewlib.lyt) after the text file(s) you just added; WabaNewAppDefs.txt (wabanewlibdefs.txt) should be before the added file(s).
7. change Project/Project Settings
   • appName: MyWabaApp (mywabalib); adjust to appropriate length title for Extras
   • appSymbol: MyWabaApp:waba (mywabalib:waba); note: this should use the name of the main class (root directory), with :waba signature (if this name is too long, use the workaround at end of app_ntk/JView3D/JView3D.cls.txt)
   • packageName: the same as appSymbol
   • icon: if the app defines its own icon, select No Resource to display the generic NTK app icon (your icon will be set in InstallScript; otherwise, it uses the generic Waba app (lib) icon)
   • see comments at top of WabaNewAppDefs.txt (wabanewlibdefs.txt) for anything else you may need to check/change
8. Project/Build Package; this generates MyWabaApp.pkg (mywabalib.pkg); check if there are any ERROR warnings in Inspector.

Create Waba apps for the Newton on the Newton

WabaTester can be used to create MyWabaApp.pkg (mywabalib.pkg) directly on the Newton, or to generate MyWabaApp.cls.txt (mywabalib.cls.txt), MyWabaApp.arg.txt () for use with a NTK project (as just described).

Requirements

• WabaTester
• WabaVM.pkg and lib_pkg/waba.pkg if you want to run MyWabaApp. Use Waba apps on the Newton
• (optional) NewtPack.pkg plugin to save package
• X-Port, Sloup, or Newt's Cape 2.1e (or greater) to transfer MyWabaApp binary files to your Newton
• (optional) EETransfer, PackageBuddy, X-Port, SimpleMail, Sloup to export MyWabaApp.pkg to your desktop
• (optional) NTK in order to transfer(Inspector) .cls.txt, .arg.txt info to desktop, and build project (.pkg)
• (future??) "javac" written in NS or Waba to generate .class from .java in Notepad/Newtworks
• MyWabaApp (2 files: warp(.class,.bmp) and exegen(parameters,icon) transferred to your Newton (e.g., Inbox) in one of the following formats:
  • Palm: .pdb and .prc
  • WinCE: .wrp and .lnk
  • Java: .jar/.class (and .htm/.html); note: only uncompressed .jar. We would recommend this format since you can include icon.bmp to create icon in Extras, and MyWabaApp.htm to provide initialization parameters, and to more easily test/distribute (Use Waba apps on the Web); a single .class file can be used instead of .jar

  Note: You would not need to provide a separate file (.prc,.lnk,.htm) for initialization parameters if

  • you include .htm and icon.bmp in .jar file
  • we provide a Newton-based preference editor
  • the default values are adequate (see wabanewton-api.txt)
  • no app icon available or generic icon ok
  • the main class name is same as the main filename
  • the classpath is not order dependent (default: all installed libraries)

Simulation

Here is a simulation of the WabaTester interface; this supports only "help mode" -- select items to see short descriptions:

	WabaTester 1.0o	App Pkg
		Lib Auto
		Pref
Apps: -- Built-in --HelloWorld (B-wrp) -- Inbox --WabaPoker (I-pdb) -- Packages -- PocketWatch (P-pkg)		NTK

Process (using EETransfer and Inbox)

1. install Newton packages
2. transfer MyWabaApp (mywabalib) "source" and parameter files: .pdb/.prc, .wrp/.lnk, .jar/.htm; use a terminal emulator on desktop (ZTerm on Macintosh; HyperTerminal on Windows) to transfer Binary files via ZModem protocol to EETransfer(Receive) on Newton
3. open WabaTester in Extras
4. select app from picker
5. check class listing, view bitmaps
6. run app and/or save app as package
7. select package in Extras, select EETransfer in action menu, Send file via ZModem to desktop terminal emulat9or

Process (using Newt's Cape)

Note: this requires at least WabaTester 1.0m and Newt's Cape 2.1e

1. open Newt's Cape
2. browse URL, e.g. Examples
3. applet appears in book with status (or error) information
4. tap "tap to transfer"
5. after .class or .jar transferred, WabaTester automatically opens
6. (optional) close Newt's Cape and your NIE connection if memory is tight
7. Launch or Save app

WabaTester Interface

Open WabaTester

in Extras, open WabaTest application

or, in Inbox, check a file, select action=Newt's Cape:Open

or, in Newt's Cape, File:Open Inbox, select file

App picker

select a Waba app in a variety of formats

Builtin: (suffix B)

built-in apps, e.g., HelloWorld, Scribble

Inbox: (suffix I)

.lnk&.wrp, .pdb (& .prc?) files, .htm/.html & .class/.jar

Package: (suffix P)

provided mainly to inspect/verify Newton packages (.pkg) with :waba signature; normally, you would launch a Waba app directly from Extras. Use Waba apps on the Newton

Info area

Each app displays the following information:

• warnings (if any), e.g., unknown main class (note: this is expected for lib)
• filename
• format (wrp, pdb, jar, class, ntk)
• byte length of entire file
• number of objects
• for each class, its name, offset, length
• for each bitmap, the same, plus width x height (tap name to view)
• args, including the app's main class name (usually same as filename)

Scroll up/down for long text; Overview button returns to beginning

tap on an image filename(.bmp) to see bitmap appear in area at top right. if bitmap is clipped, tap on it to popup a complete picture

Launch VM button

sets classpath (lookup context) to include other installed libraries, e.g., lib_pkg/waba.pkg and launches VM (if installed)

Close VM button

cleans up dynamic context, and shuts down VM; alternatively, you could close your app directly via its close box

Save button

saves current class info, depending on radio buttons

App Pkg

saves current file to a Newton package, assuming NewtPack is installed it copies current settings and a couple of methods. it quits WabaTester to increase heap and avoid problems with munged data. to export package to desktop, use EETransfer or other upload tool.

Lib Auto

saves as an autopart, e.g., lib_pkg/waba.pkg or other library packages

Pref

if you have changed heap or other settings via WabaVM preference panel, this prints app's current preference settings so that you can modify the app's parameters before you next save and distribute

NTK

prints current app (lib) to NTK Inspector (assuming it's open) in MyWabaApp.cls.txt (mywabalib.cls.txt) and MyWabaApp.arg.txt () format; copy/paste into text files and save in MyWabaApp (mywabalib) project folder

• Use/Create Newton Waba Applications! this page
• Sean Luke Newton VM, Preference Editor
• Sean's Waba Newton page
• Steve Weyer WabaTester, Warp/Exegen/GUI