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
• app.find
• app.hide
• app.key
• app.open
• app.runs
• app.send
• app.show
• app.start
• app.stop
• app.view
• Constants

app.capture

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

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

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

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

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

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

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

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

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

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

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