WabaVM/WabaApp API

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

Last updated: 25-Jun-2005

WabaVM refers to the application (symbol: |vm:waba|);
WabaApp refers to any saved Waba application or WabaTester (symbol: |WabaTester:waba|).

launchWabaVM

Context: called by WabaApp.viewSetupFormScript(Extras 'open'),
	or WabaTester.appLaunch"(Launch VM" button)

Action: launches WabaVM with specified Waba app, and returns vm value;
this should be saved for later use in shutDownWabaVM and VMExited.

Example:
	vm := GetRoot().|vm:waba|:?launchWabaVM("HelloWorld", {}, self);

API:
/*vmBinary*/ WabaVM:launchWabaVM(/*string*/ appMainName, /*frame*/ appArgs, /*wabaApp*/ wabaApp)

Parameters:
appMainName: class name of the main class
(with possible package info, but no .class extension)
this is usually the same as original container filename, but not necessarily

appArgs: frame with optional initialization parameters
in addition to description and default, this shows mapping from likely initialization files
{
width: /*int*/,		// requested width  of the Java drawing area Default: 160
 	/w (.lnk,.prc?), width=(.htm)
height: /*int*/,		// requested height of the Java drawing area Default: 160
 	/h (.lnk,.prc?), height=(.htm)

vmStackSize: /*int*/,		// default: 1500
 	/s (.lnk,.prc?), vmstacksize=(.htm)
nmStackSize: /*int*/,		// default: 300
 	/t (.lnk,.prc?), nmstacksize=(.htm)
classHeapSize: /*int*/,	// default: 14000
 	/l (.lnk,.prc?), classheapsize=(.htm)
objectHeapSize: /*int*/,	// default: 8000
 	/m (.lnk,.prc?), objectheapsize=(.htm)

archive: /*string[]*/,	// used by app (but not VM). classpath of required libraries (with no extensions). default: waba
 	/w (.lnk,.prc?), archive=(.htm)

uniqueSymbol: /*symbol*/  	// the symbol that preferences for the app will be based on.
				    		// default: |wabaApp-CLASSNAMEHERE:waba|

wantsGray: /*int: 1 or 0*/, // Default: 0

useCPlusPlusHeap: *int: 1 or 0*/,	// allocate Java classes on the C++ heap?  Default: 0

doubleBuffer: *int: 1 or 0*/,	// double-buffer? (grab bitmaps from windows)  Default: 0
}
 
wabaApp: an application frame
e.g., GetRoot().|WabaTester:waba| or GetRoot().|HelloWorld:waba|
that can respond to the messages: getWabaClass,
getResource, and VMExited.

shutdownWabaVM

Context: called by WabaApp.viewQuitScript(Extras 'toggle' i.e., close),
	or WabaTester.appShutdown("Close VM" button).

Action: shuts down WabaVM. If app received earlier VMExited, 
then this does nothing (i.e., VM already shut down).

Example:
	GetRoot().|vm:waba|:?shutdownWabaVM(vm);

API:
/*void*/ WabaVM:shutdownWabaVM(/*vmBinary*/ vm)

Parameter:
vm: saved value returned by launchWabaVM.

RemovePreferences

Context: called by a WabaApp, typically in DeletionScript

Action: vm removes any preferences related to the app

Example:
	GetRoot().|vm:waba|:?RemovePreferences(kAppMainName, kAppSymbol);

API:
/*void*/ WabaVM:RemovePreferences(/*string*/ mainAppName, /*symbol*/ appSymbol)

Parameters:
mainAppName: name of main class; same as passed to launchWabaVM
	
appSymbol: a unique symbol, usually the package symbol

Note: since WabaVM may not be installed, it's now recommended that an app
remove the preference frame directly:

DeletionScript := func()
	//GetRoot().(kWabaVMSymbol):?RemovePreferences(kAppMainName, kAppSymbol);
	EntryRemoveFromSoupXmit (GetAppPrefs(kAppSymbol, {}), nil);

VMexited

Context: called by a WabaVM

Action: if the vm matches the one saved from launchWabaVM by WabaApp,
then WabaApp should close; it should also reset vm so that close skips shutdownWabaVM.

Example:
	WabaApp:VMexited(vm);

API:
/*void*/ WabaApp:VMExited(/*vmBinary*/ vm)

Parameter:
vm: the instance of vm that has just exited (shut down)

getWabaClass

Context: called by a WabaVM

Action: if class found in WabaApp (or library), returns:
	{
	class:	/*binary*/,
	offset: /*int*/,
	length: /*int*/,
	}
otherwise: nil

Examples:
	classEntry := GetRoot().|WabaTester:waba|:getWabaClass("HelloWorld");
	classEntry := WabaApp:getWabaClass("waba/ui/Edit");

API:
/*classEntryFrame*/ WabaApp:getWabaClass(/*string*/ className)

Parameter:
className: name of class, with possible package info, but without .class extension

getResource

Examples: 

Context: called by a WabaVM

Action: if bitmap found in WabaApp, returns 2.x compatible bitmap frame
	{
	class:	'bitmap,
	...,
	}
otherwise: nil

Examples:
	bitmap := GetRoot().|WabaTester:waba|:getResource("test.bmp");
	bitmap := WabaApp:getResource("myPkg/images/one.bmp");

API:
/*bitmapFrame*/ WabaApp:getResource(/*string*/ imageName)

Parameter:
imageName: a BMP file, with .bmp extension, possible package/path.

Note: Currently, getWabaClass and getResource use the same method, i.e., name (unchecked) returns a frame -- class or bitmap -- or nil.

Libraries

A library is an Extension that installs itself in a global variable. When a WabaApp opens, it establishes a "classpath" that includes itself and installed libraries -- either all, or only those specified in the ARCHIVE attribute parameter. This is used during lookup by getWabaClass.

Internally, the global variable looks like: 

/*frame*/ GetGlobalVar('|vm:waba|).lib
  {
  waba:   {... appContext: {}...},
  wextra: {... appContext: {}...},
  }
[Top: TOC] | launchWabaVM | shutdownWabaVM | RemovePreferences | VMExited | getWabaClass | getResource | [Libraries]