This component keeps track of information useful when launching applications: it keeps track of how much memory is available and how well sleeping applications fit into that memory. This component resides in the system module. Thus, to interact with it, your program will probably use a syntax like that in the following example:
system:launcher!RequestMemory( 2 ) REM We'll need another 2K soon
Applications which will handle Launcher events can create their own Launcher components.
Standard Properties
class, parent, proto, version.
memoryAvailable integer
This read-only property reflects the estimated amount of free heap memory available for loading applications.
The value decreases when applications are loaded, and increases when they are unloaded.
When this value becomes negative _memoryDemand() events will be raised, which cause the system to attempt to unload sleeping applications. This should get memoryAvailable back above zero.
The memoryAvailable value is typically less than the actual amount of free memory, as the system needs to keep a certain amount in reserve to allow for fragmentation and sudden rushes in memory use before protection mechanisms can react.
memoryReserve integer
This read-only property holds the amount of memory to subtract from the true number of free kilobytes when calculating memoryAvailable.
Designed to insure that there is always some memory around when memoryAvailable becomes negative. Specifically, this value has to be large enough such that if memoryAvailable is sitting at 0, and a large allocation occurs, there will be enough memory left to unload applications before we actually run out of memory.
_hardIconPressed( self AS launcher, icon AS integer )
This event is generated when the user presses one of the device's "hard icons." Typically, an application's Launcher won't do anything at this point, but will instead allow the system Launcher to do its thing.
self launcher
The component experiencing the event
icon integer (range is device-specific)
Which icon was tapped.
_hide( self AS launcher, application AS string )
The launcher should respond to this event by hiding the named application. This normally means calling that application's module_hide() routine, and the module_show() routine of some other application.
_memoryDemand( self AS launcher, memoryDemanded AS integer )
This event is generated whenever memoryAvailable becomes negative--however, if there is more than one Launcher component active on the device when this happens, not all of them will necessarily detect this event. The youngest Launcher will first have a chance to handle the event--if it can free up enough memory such that memoryAvailable goes positive, then other launchers will never generate the event. If it can't free up enough memory, the next youngest Launcher will generate the event, and get its chance to free up memory. Finally, if no other Launcher can free up enough memory, the system Launcher will unload some applications.
When this event is generated, any flushable applications in the cache should already have been flushed by the _memoryRequest() handler in the system module.
Chances are, there is an application that is using too much memory; it should now be unloaded (with apology) to the user. The next possibility is that too many apps are attempting to keep from being unloaded by setting preventUnload to non-zero. These should be unloaded at this time, because the system is very low on memory.
self launcher
The component experiencing the event.
memoryDemanded integer(0-32767)
The amount of memory, in kilobytes, demanded.
_memoryRequest( self AS launcher, memoryNeeded AS integer )
This event is generated whenever a RequestMemory() action is invoked that requests more memory than is available. If possible, sufficient memory to honor the request should be freed up in this handler.
Applications or modules that can reduce the amount of memory they are using can have their own Launcher component, and handle this event by reducing their memory usage. Otherwise, the system Launcher component may unload some applications that are currently loaded but not in use.
If there is more than one Launcher component, the memoryRequest event will be generated for as many of them as it takes to free up the requested memory. The components will generate the events in order from youngest to oldest. The system module's Launcher component will get the event last, after any loaded applications free as much memory as they can.
self launcher
The component experiencing the event.
memoryDemanded integer (0-32767)
The amount of memory demanded, measured in kilobytes.
_outOfMemory( self AS launcher )
This event is generated if the system is in dire trouble. If an application has demanded memory, and no Launcher has been able to free up enough memory, this event is generated. The system has severe memory problems, perhaps severe fragmentation or a memory leak.
After all applications' Launchers have had their chance to handle this event, the system Launcher module will apologize to the user and reboot.
self Launcher
The component experiencing the event.
_setContext( self AS launcher, application AS string, context AS string )
This event is generated when the Launcher tries to "go to" a specific context within a specific application. The application should be brought to the front if running, loaded if it's not running. The typical handler for this event will do what the handler for the _switchTo() event does, except that it will pass the supplied context string to the application's module_goTo() routine.
self launcher
The component experiencing the event.
application string
A module locator string for the governing module of an application, like those passed to LoadModule().
context string
Context as passed to the module_goTo() routine of the application module. The null string ("") may be passed to invoke the application in its initialized state.
_switchTo( self AS launcher, application AS string )
This event is generated when this Launcher wants to switch to an application, as the result of the SwitchTo() action. A handler for this action will normally proceed as follows:
application string
The application to hide.
RequestMemory( memoryRequested AS integer ) AS integer
Requests that the system free memory for upcoming use. This action, intelligently used, can minimize user-perceived delays.
This function is good to call from strategic points in an application where the application knows it will need more memory soon and the user is likely to tolerate a delay.
If sufficient memory was not freed, then the action will return zero.
SetContext( application AS string, context AS string )
Use this action to go to a particular context within a specified application.
If you're using your own Launcher component, this action will generate a _setContext() event.
SwitchTo( application AS string ) AS string
Use this action to switch to an application: to load the application if it's not already loaded, and to bring it to the front.
If you're using your own Launcher component instead of the system's Launcher, invoking this event generates a SwitchTo() action.