waba.sys
Class Vm

java.lang.Object
  |
  +--waba.sys.Vm

public final class Vm

extends java.lang.Object

Vm contains various system level methods.

This class contains methods to copy arrays, obtain a timestamp, sleep and get platform and version information, among other things.

Field Summary

static boolean	actionEqualsMenu Internal use only
static boolean	disableDebug Set to true to disable Vm.debug message output.
static java.lang.String	ERASE_DEBUG Pass this to Vm.debug to erase the memo/txt file used to store the output.
static int	interceptSystemKey Only available at desktop. used internally.
static int	SK_ACTION used as constant that can be 'or'ed in the interceptSystemKeys method.
static int	SK_ALL used as constant that can be 'or'ed in the interceptSystemKeys method.
static int	SK_CALC used as constant that can be 'or'ed in the interceptSystemKeys method
static int	SK_CLOCK used as constant that can be 'or'ed in the interceptSystemKeys method.
static int	SK_CONTRAST used as constant that can be 'or'ed in the interceptSystemKeys method.
static int	SK_FIND used as constant that can be 'or'ed in the interceptSystemKeys method
static int	SK_HARD1 used as constant that can be 'or'ed in the interceptSystemKeys method.
static int	SK_HARD2 used as constant that can be 'or'ed in the interceptSystemKeys method.
static int	SK_HARD3 used as constant that can be 'or'ed in the interceptSystemKeys method.
static int	SK_HARD4 used as constant that can be 'or'ed in the interceptSystemKeys method.
static int	SK_LAUNCH used as constant that can be 'or'ed in the interceptSystemKeys method
static int	SK_NONE used as constant that can be 'or'ed in the interceptSystemKeys method
static int	SK_PAGE_DOWN This one also can be used in the getSystemKeysPressed method.
static int	SK_PAGE_LEFT used as constant that can be 'or'ed in the interceptSystemKeys method.
static int	SK_PAGE_RIGHT used as constant that can be 'or'ed in the interceptSystemKeys method.
static int	SK_PAGE_UP This one also can be used in the getSystemKeysPressed method.
static int	SK_SYNC used as constant that can be 'or'ed in the interceptSystemKeys method.
static int	TWEAK_AUDIBLE_GC To be used in the tweak method.
static int	TWEAK_CHECK_LEAK To be used in the tweak method.
static int	TWEAK_DEBUG_TO_NVFS To be used in the tweak method.
static int	TWEAK_DUMP_MEM_STATS To be used in the tweak method.
static int	TWEAK_PRINT_STACK To be used in the tweak method.

Method Summary

static boolean	attachLibrary(java.lang.String name) Attaches a library to this application instance.
static boolean	attachNativeLibrary(java.lang.String name) Attaches a native library to this application instance (only works at device).
static void	clipboardCopy(java.lang.String s) copies the specific string to the clipboard
static java.lang.String	clipboardPaste() gets the last string from the clipboard. if none, returns "".
static boolean	copyArray(java.lang.Object srcArray, int srcStart, java.lang.Object dstArray, int dstStart, int length) Copies the elements of one array to another array.
static void	debug(java.lang.String s) Sends a text, preceeded with the current time stamp and followed by a line feed, to: The "SuperWaba Debug Console" memo on Palm OS The "DebugConsole.txt" file on WinCE/Win32 systems The console, in JDK You can delete the debug memo/txt file passing the ERASE_DEBUG, a constant String declared in this class.
static int	exec(java.lang.String command, java.lang.String args, int launchCode, boolean wait) Executes a command.
static void	exitAndReboot() Reboots the device.
static void	gc() Calls the Garbage Collector.
static int	getDeviceFreeMemory() returns the free memory in the device.
static byte[]	getFile(java.lang.String name) Returns a byte array of a file contained in the same pdb where this one resides, or in some attached library.
static int	getRemainingBattery() Returns the percentage of the remaining battery life of this device.
static int	getSystemKeysPressed() Gets the current keys being pressed.
static int	getTimeStamp() Returns a time stamp in milliseconds.
static void	interceptSystemKeys(int keys) Specify which system keys to intercept. use the SK_xxx constants ored together. eg: interceptSystemKeys(HARD1 | HARD2 | FIND).
static int	setDeviceAutoOff(int seconds) Sets the device's "auto-off" time.
static void	setTimeStamp(Time t) Sets the system time to the given arguments.
static void	sleep(int millis) Causes the VM to pause execution for the given number of milliseconds.
static void	tweak(int param, boolean set) Tweak some parameters of the virtual machine.
static void	warning(java.lang.String s) This function can be used to show permanent warnings.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

SK_PAGE_UP

public static final int SK_PAGE_UP

This one also can be used in the getSystemKeysPressed method.

SK_PAGE_DOWN

public static final int SK_PAGE_DOWN

This one also can be used in the getSystemKeysPressed method.

SK_HARD1

public static final int SK_HARD1

used as constant that can be 'or'ed in the interceptSystemKeys method. This one also can be used in the getSystemKeysPressed method.

SK_HARD2

public static final int SK_HARD2

used as constant that can be 'or'ed in the interceptSystemKeys method. This one also can be used in the getSystemKeysPressed method.

SK_HARD3

public static final int SK_HARD3

used as constant that can be 'or'ed in the interceptSystemKeys method. This one also can be used in the getSystemKeysPressed method.

SK_HARD4

public static final int SK_HARD4

used as constant that can be 'or'ed in the interceptSystemKeys method. This one also can be used in the getSystemKeysPressed method.

SK_LAUNCH

public static final int SK_LAUNCH

used as constant that can be 'or'ed in the interceptSystemKeys method

SK_FIND

public static final int SK_FIND

used as constant that can be 'or'ed in the interceptSystemKeys method

SK_CALC

public static final int SK_CALC

used as constant that can be 'or'ed in the interceptSystemKeys method

SK_ACTION

public static final int SK_ACTION

used as constant that can be 'or'ed in the interceptSystemKeys method.

SK_CONTRAST

public static final int SK_CONTRAST

used as constant that can be 'or'ed in the interceptSystemKeys method.

SK_CLOCK

public static final int SK_CLOCK

used as constant that can be 'or'ed in the interceptSystemKeys method.

SK_SYNC

public static final int SK_SYNC

used as constant that can be 'or'ed in the interceptSystemKeys method. Synchronize button for Palm OS only.

SK_ALL

public static final int SK_ALL

used as constant that can be 'or'ed in the interceptSystemKeys method. Note: SK_ALL does not intercept the SK_LAUNCH, SK_CONTRAST, SK_CLOCK and SK_SYNC keys (to maintain compatibility with older applications. You must use SK_ALL | SK_LAUNCH (or other excluded SK_) to intercept the home key.

SK_NONE

public static final int SK_NONE

used as constant that can be 'or'ed in the interceptSystemKeys method

SK_PAGE_LEFT

public static final int SK_PAGE_LEFT

used as constant that can be 'or'ed in the interceptSystemKeys method. This one also can be used in the getSystemKeysPressed method. This key works only in Windows CE and Palm OS 5 or greater.

Since:

SuperWaba 3.0

SK_PAGE_RIGHT

public static final int SK_PAGE_RIGHT

used as constant that can be 'or'ed in the interceptSystemKeys method. This one also can be used in the getSystemKeysPressed method. This key works only in Windows CE and Palm OS 5 or greater.

Since:

SuperWaba 3.0

interceptSystemKey

public static int interceptSystemKey

Only available at desktop. used internally. Dont set it directly, it will have no effect.

actionEqualsMenu

public static boolean actionEqualsMenu

Internal use only

ERASE_DEBUG

public static java.lang.String ERASE_DEBUG

Pass this to Vm.debug to erase the memo/txt file used to store the output.

disableDebug

public static boolean disableDebug

Set to true to disable Vm.debug message output. Note that the method calls will still remain, and can slowdown your algorithm. Note also that Vm.warning is not affected by this flag.

Since:

SuperWaba 5.52

TWEAK_AUDIBLE_GC

public static final int TWEAK_AUDIBLE_GC

To be used in the tweak method.

TWEAK_DUMP_MEM_STATS

public static final int TWEAK_DUMP_MEM_STATS

To be used in the tweak method.

TWEAK_CHECK_LEAK

public static final int TWEAK_CHECK_LEAK

To be used in the tweak method.

TWEAK_PRINT_STACK

public static final int TWEAK_PRINT_STACK

To be used in the tweak method.

TWEAK_DEBUG_TO_NVFS

public static final int TWEAK_DEBUG_TO_NVFS

To be used in the tweak method.

Method Detail

copyArray

public static boolean copyArray(java.lang.Object srcArray,
                                int srcStart,
                                java.lang.Object dstArray,
                                int dstStart,
                                int length)

Copies the elements of one array to another array. This method returns true if the copy is successful. It will return false if the array types are not compatible or if either array is null. If the length parameter would cause the copy to read or write past the end of one of the arrays, an index out of range error will occur. If false is returned then no copying has been performed.

Parameters:

srcArray - the array to copy elements from

srcStart - the starting position in the source array

dstArray - the array to copy elements to

dstStart - the starting position in the destination array

length - the number of elements to copy

getTimeStamp

public static int getTimeStamp()

Returns a time stamp in milliseconds. The time stamp is the time in milliseconds since the program started. The maximum time stamp value is (1 << 30) and when it is reached, the timer will reset to 0 and will continue counting from there.

setTimeStamp

public static void setTimeStamp(Time t)

Sets the system time to the given arguments. Note that in some systems, the millis field is ignored. Some devices require that you add Settings.timeZone.

Since:

SuperWaba 4.01

exitAndReboot

public static void exitAndReboot()

Reboots the device. This is the equivalent of a warm boot (or soft reset). Calling this method terminates the program, closes all open files and, finaly, resets the device (MainWindow.onExit is still called). In JDK, this is equivalent to the MainWindow.exit method (there's no reboot at all).

Since:

SuperWaba 4.01

exec

public static int exec(java.lang.String command,
                       java.lang.String args,
                       int launchCode,
                       boolean wait)

Executes a command.

As an example, the following call could be used to run the command "scandir /p mydir" under Java, Win32 or WinCE:

 int result = Vm.exec("scandir", "/p mydir", 0, true);
 

This example executes the Scribble program under PalmOS:

 Vm.exec("Scribble", null, 0, false);
 

This example executes the web clipper program under PalmOS, telling it to display a web page by using launchCode 54 (CmdGoToURL).

 Vm.exec("Clipper", "http://www.yahoo.com", 54, true);
 

The args parameter passed to this method is the arguments string to pass to the program being executed.

The launchCode parameter is only used under PalmOS. Under PalmOS, it is the launch code value to use when the Vm calls SysUIAppSwitch(). If 0 is passed, the default launch code (CmdNormalLaunch) is used to execute the program.

The wait parameter passed to this method determines whether to execute the command asynchronously. If false, then the method will return without waiting for the command to complete execution. If true, the method will wait for the program to finish executing and the return value of the method will be the value returned from the application under Java, Win32 and WinCE.

Under PalmOS, the wait parameter is ignored since executing another program terminates the running program.

Note: this method kills all running threads.

To run another SuperWaba program from Windows CE devices, use:

 Vm.exec("\\SuperWaba\\SuperWaba.exe","ProgName Path creatorid", 0, false);
 

To run another SuperWaba program from Palm OS devices, use:

 Vm.exec("SuperWaba","ProgName creatorid", 0, false);
 

In other words, you must mimic the command in the .lnk file created with Exegen.

When calling a SuperWaba program, you can pass a command line parameter to the calling application, just placing the parameters after the creatorid one. It can be retrieved with getCommandLine method from the MainWindow.

In some platforms, the caller application must be quit by calling exit.

Parameters:

command - the command to execute

args - command arguments

launchCode - launch code for PalmOS applications

wait - whether to wait for the command to complete execution before returning

setDeviceAutoOff

public static int setDeviceAutoOff(int seconds)

Sets the device's "auto-off" time. This is the time in seconds where, if no user interaction occurs with the device, it turns off. To keep the device always on, pass 0. This method only works under PalmOS. The integer returned is the previous auto-off time in seconds. Remember to restore it when the program exit.

sleep

public static void sleep(int millis)

Causes the VM to pause execution for the given number of milliseconds.

Parameters:

millis - time to sleep in milliseconds

getDeviceFreeMemory

public static int getDeviceFreeMemory()

returns the free memory in the device. This memory is where the database info is stored.

Since:

SuperWaba2.0beta4

gc

public static void gc()

Calls the Garbage Collector. Usualy, this isnt necessary; the gc is called everytime theres no more memory to allocate

interceptSystemKeys

public static void interceptSystemKeys(int keys)

Specify which system keys to intercept. use the SK_xxx constants ored together. eg: interceptSystemKeys(HARD1 | HARD2 | FIND). You can also use SK_ALL or SK_NONE as parameter. Note that the constants differ from the ones in IKeys. in the event handler, you must check for the IKeys values (eg: IKeys.HARD1).

Since:

SuperWaba2.0beta3

debug

public static void debug(java.lang.String s)

Sends a text, preceeded with the current time stamp and followed by a line feed, to:

• The "SuperWaba Debug Console" memo on Palm OS
• The "DebugConsole.txt" file on WinCE/Win32 systems
• The console, in JDK

You can delete the debug memo/txt file passing the ERASE_DEBUG, a constant String declared in this class. E.g.: Vm.debug(Vm.ERASE_DEBUG);.

Note: if you're debugging a String that contains \0 in it, all chars after the first \0 are ignored.

warning

public static void warning(java.lang.String s)

This function can be used to show permanent warnings. It was created because Vm.debug is, in theory, just for debugging. Some SuperWaba classes displays warnings to the user, and are not debug (i.e., temporary) messages. It just calls Vm.debug("Warning! "+s), so it differs from it only in a semanthical way.

Note: you cannot use this function with ERASE_DEBUG; it won't work.

Since:

SuperWaba 4.21

clipboardCopy

public static void clipboardCopy(java.lang.String s)

copies the specific string to the clipboard

clipboardPaste

public static java.lang.String clipboardPaste()

gets the last string from the clipboard. if none, returns "".

attachLibrary

public static boolean attachLibrary(java.lang.String name)

Attaches a library to this application instance. This is useful if you have a local or global library and want to make its classes available to your app. At the initialization, SuperWaba scans all libraries in the device and automatically attach them. But, if the library you're using have a different creator ID or if you saved a bitmap into a file, you may need to attach the file where it is located so you can instantiate its classes or load it using new Image(filename).

Note: this method only attaches SuperWaba Local Extension Libraries, ie, files that have the app's creator id and type 'SWAX'. You may also specify another creator id to the name by adding it like "name.crtr". This make possible the use of a local library in another programs (eg: libA used by progB and progC). In the dekstop you must use "name.crtr", otherwise the library will not be loaded.

After a library is added, its file cannot be modified.

To see what libraries are in the device, you can use Catalog.listCatalogs() and check the files that has type 'SWAX'.

At the desktop, you may attach a library to load an image stored in a Catalog. In Palm OS, if you try to attach the library more than once, it will attach and return true, but only the first instance will be really used. In Windows CE, attaching for the second time will fail.

Returns:

true if the library was found and attached, false otherwise.

attachNativeLibrary

public static boolean attachNativeLibrary(java.lang.String name)

Attaches a native library to this application instance (only works at device). You must attach the native library before use any native methods from your library, otherwise you'll get errors like "cannot find native method implementation for ...". To learn how to create a native library, you can purchase the Library Tutorial. See at www.superwaba.org. In desktop, always returns true. Starting on version 5.0, a check is made to see if the native library was already loaded, returning true if positive.

getSystemKeysPressed

public static int getSystemKeysPressed()

Gets the current keys being pressed. You must set which keys you want to receive notification with the interceptSystemKeys method. Note that you can use this method to verify if more than one key is pressed at once, just keep pooling with this method to see when a state has changed. If you just want to intercept the key with a single press, handle it in the onEvent method, with a KeyEvent event.

See Also:

SK_PAGE_UP, SK_PAGE_DOWN, SK_PAGE_LEFT, SK_PAGE_RIGHT, SK_ACTION, SK_HARD1, SK_HARD2, SK_HARD3, SK_HARD4, interceptSystemKeys(int)

getFile

public static byte[] getFile(java.lang.String name)

Returns a byte array of a file contained in the same pdb where this one resides, or in some attached library. The returned array is a fake pointer; does NOT point directly to the file (a new buffer is created to store the contents). Example:

 byte []b = Vm.getFile("waba/ui/About.txt");
 if (b != null)
    popupModal(new MessageBox("About",new String(b,0,b.length)));
 

Warp will insert the .txt file into the program's pdb.

Returns:

a byte array with the file or null if file not found

getRemainingBattery

public static int getRemainingBattery()

Returns the percentage of the remaining battery life of this device. In systems that can have an auxiliary battery, it will return the sum of the main and the auxiliary battery, but this sum will always be limited to 100%. In desktop, it will always return 100. Note that in some OSes, when on the cradle, the returned value may be 100% even when charging.

Since:

SuperWaba 4.21

tweak

public static void tweak(int param,
                         boolean set)

Tweak some parameters of the virtual machine. These parameters can be set also running the Welcome application, and going to the vm menu options. See the TWEAK_xxx constants to know which options are available. Note that these parameters are only available at the device, NOT when running as Java. Also, the configuration is not persisted: you must set this every time you run the program.

Since:

SuperWaba 5.82