Prev: Applications and Processes
Module app: Application Control
This module provides access to the applications installed on the phone: listing installed applications, opening documents, starting and stopping applications, and bringing them to the foreground or sending them to the background.
Functions in this module are specific to Symbian OS, and not likely to be portable to other operating systems.
In Symbian OS, each application has its unique UID (unique identifier), which is simply an integer number. In the functions of this module, an application is identified by its UID or its name (caption). Since the caption is language and installation dependent, the UID is generally preferrable. Application UIDs and captions may also vary between different devices.
Since m itself is also an application, the functions in this module can also be used to bring m to the foreground, send it to background, or simply stop it. The app.uid constant identifies the m application.
app.capture
• function capture(key, upsAndDowns=false) → null
Permissions: WriteApp
Capabilities: extended
Registers a certain key event, for processing by ui.cmd, regardless whether m has the keyboard focus or not. If key>0 the capturing is enabled, a key<0 disables the key capturing. Throws ErrAlreadyExists if capturing is requested by m more than ones for the same key. Therefore, it is a good praxis always first to disable the capturing before requesting it.
// request capturing for camera key (S60)
app.capture(-0xf880)
app.capture(0xf880)
|
- If upsAndDowns=false, m receives, respectively ui.cmd returns, the key code for a complete keystroke. See also ui.keys.
- If upsAndDowns=true, m receives a positive scan code if key is pressed, and a negative scan code if the key is released.
app.find
• function find(name=null) → Array
Permissions: ReadApp
Searches for applications whose name matches the pattern name. name is not case sensitive and can contain the wildcards * and ?. If name=null, searches for all installed applications.
Returns an array with one element for each application found, each element being an array with the following keys:
| Key | Meaning | Type |
| name | Application name (caption) | String |
| file | Application DLL file name | String |
| uid | Application UID | Number |
| |
// search for the mShell application
for a in app.find("mShell") do
print a
end
→ [mShell,C:\System\Apps\mShell\mShell.app,270549657]
|
app.hide
• function hide(uidOrName) → null
Permissions: ReadApp
Hides the application identified by uidOrName, i.e. sends it to the background. uidOrName can be the application's UID, or its name (caption).
Throws ErrNotFound if the application does not exist.
// hide the messaging application
app.hide("Messaging")
|
app.key
• function key(scancodes) → null
Permissions: ReadApp+WriteApp
Capabilities: extended
• function key(keycodes, uidOrName) → null
Permissions: ReadApp+WriteApp
Capabilities: extended
Sends a keyboard event or a series of keyboard events to the device or to a specific application.
With one argument, sends scancodes to the device. scancodes can be a single integer, an array of integers, or a string. A positive integer causes a press of the key with this scan code, a negative integer a release of the key with this scan code (after changing its sign). Scan codes are OS and device specific. Use ui.cmd after calling ui.keys(true) to obtain the scan code for a specific key.
With two arguments, sends keycodes to the application defined by uidOrName. keycodes can be a single integer, an array of integers, or a string. Each integer or character causes a stroke of the key with this code. Most key codes correspond to character codes, but some codes are reserved for device specific keys. Use ui.cmd after calling ui.keys(false) to obtain the key code for a specific key.
// Start the contacts application and send it a name
app.start("Contacts"); app.key("William", "Contacts")
// Simulate flip close and open on UIQ
app.key(0x77); sleep(2000); app.key(0x76)
// Show profile selection via power key on S60
app.key([0xa6, -0xa6])
|
app.open
• function open(file, uidOrName=null) → Number
Permissions: Read+Write(file)+ReadApp+WriteApp
| | |
| Compatibility of function app.open |
| Sony Ericsson UIQ3 phones cannot handle uidOrName#null. | ErrNotSupported |
|
Opens a file, using the application defined by uidOrName. uidOrName can be the application's UID, or its name (caption). If uidOrName=null, the standard application for files of this type is used.
Returns the UID of the started application.
Throws ErrNotFound if the application does not exist.
// show an image file in the standard image viewer
uid=app.open("mShell.png");
// kill the app after ten seconds
sleep(10000); app.stop(uid)
|
app.runs
• function runs(uidOrName) → Boolean
Permissions: ReadApp
Checks whether the application defined by uidOrName is running. uidOrName can be the application's UID, or its name (caption).
Throws ErrNotFound if the application does not exist.
// check whether the phone application is running
// the caption is in german...
app.runs("Telefon")
→ true
|
app.send
• function send(uidOrName, msgUid, params) → null
Permissions: ReadApp+WriteApp
Capabilities: extended
Send a message to the application defined by uidOrName. uidOrName can be the application's UID, or its name (caption). msgUid must be an integer identifying the message type, and params must be a string whose bytes define the message.
Throws ErrNotFound if the application does not exist or is not running.
This function is completely Symbian OS specific; using it requires additional information typically found in the Symbian OS SDKs. See also app.view.
// have the WML browser open a link
// WML browser has UID 0x10008d39 on S60
app.send(0x10008d39, 0, "http://wap.248.ch")
|
app.show
• function show(uidOrName) → null
Permissions: ReadApp+WriteApp
Shows the application identified by uidOrName, i.e. brings it to the foreground. uidOrName can be the application's UID, or its name (caption).
Throws ErrNotFound if the application does not exist or is not running.
// make sure the mShell application is shown
app.show(app.uid)
|
app.start
• function start(uidOrName, background=false) → null
Permissions: ReadApp+WriteApp
Starts the application identified by uidOrName. uidOrName can be the application's UID, or its name (caption). If background=true, the application is started in the background, otherwise it is brought to the foreground.
Throws ErrNotFound if the application does not exist.
// start the WML browser in the background
// WML browser has UID 0x10008d39 on S60
app.start(0x10008d39, true)
|
app.stop
• function stop(uidOrName) → null
Permissions: ReadApp
Stops (ends) the application identified by uidOrName. uidOrName can be the application's UID, or its name (caption).
Throws ErrNotFound if the application does not exist.
// stop the WML browser
// WML browser has UID 0x10008d39 on S60
app.stop(0x10008d39)
|
app.view
• function view(uidOrName, viewUid) → null
Permissions: ReadApp
• function view(uidOrName, viewUid, commandUid, params) → null
Permissions: ReadApp+WriteApp
Switches to a view viewUid of the application identified by uidOrName. uidOrName can be the application's UID, or its name (caption).
With four parameters, sends the view the command commandUid and the bytes of the string params.
Throws ErrNotFound if the application does not exist.
This function is completely Symbian OS specific; using it requires additional information typically found in the Symbian OS SDKs.
function showcontact(id)
// build the parameter block
params=[1]; // EFocusedContactId
// encode the id as four byte integer
for i=1 to 4 do
append(params, id & 0xff); id = id shr 8
end;
app.view(0x101f4cce, // Phonebook application UID
4, // focused view
0x101f4ccf, // command UID
char(params)) // params must be string
end
showcontact(114)
|
app Constants
• const uid = 0x10204299 | 0xa0002f97 | 0xe7e0cab7
The UID of the
m application.
Next: Module async: Asynchronous Function Streams© 2004-2011 airbit AG, CH-8008 Zürich
Document AB-M-LIB-888
