Prev: Module light: Control Device Lighting

Module `ui`: User Interface Functions

This module provides functions to display standard dialogs and menus and to modify the m user interface.

`ui.busy`

• function busy(activity) → null
• function busy() → null

With one argument, shows a popup window with the text activity, indicating that something is going on. Without an argument, discards the popup window.

Both calls return immediately.

ui.busy("Wait five seconds"); // show a popup window sleep(5000); ui.busy() // discard the window


Series 60 sample screen		UIQ sample screen

`ui.cmd`

• function cmd(timeout=-1) → Number|String|Array|null

This function waits for a user command or action:

A key press, release, or complete keystroke: the function returns the positive scan code for a key press, the negative scan code for a release, or the key code for a keystroke.
For characters, both scan codes and key codes typically correspond to their UNICODE® number, and can thus be converted with .char. Codes for navigation and system keys are device specific. Some important keys are defined as constants (see * ()).
ui.keys must have been called before to declare interest in such keyboard input.
A script specific menu command being selected by the user: the function returns the corresponding string from the menu.
ui.menu must have been called before to set up the menu.
The user touches the screen with the pointing device or moves it: the function returns an array with the following elements:
Key Meaning

x x-coordinate of pointer

y y-coordinate of pointer

buttons mask of pressed buttons: bit 0 for button 1, bit 1 for button 2, bit 2 for button 3.

ui.ptr must have been called before to declare interest in such pointer input.

If a monitored user action (keystroke, menu selection, pointing) occurred before ui.cmd is called, it immediately returns the corresponding result.

If timeout>=0 and timeout milliseconds have passed without response from the user, null is returned. Throws ExcValueOutOfRange if ms exceeds 2147483 (35 minutes and 47.483 seconds).

Keyboard, menu and pointer can all be monitored together in a single ui.cmd call.

See ui.keys for an example using the keyboard, ui.menu for an example using menus, ui.ptr for an example using the pointer.

`ui.confirm`

• function confirm(question, title="mShell") → Boolean

Shows a simple dialog displaying question in a dialog with title title. The dialog asks the user for confirmation, presenting two buttons or soft keys with the options "yes" and "no".

Returns true if the user answers "yes", and false if the user answers "no".

name="labels.txt"; if ui.confirm("Really delete " + name + "?") then files.delete(name) end


Series 60 sample screen		UIQ sample screen

`ui.error`

• function error(message) → null

Displays a dialog with the error message, waiting until the user presses the "continue" button or a key.

adr="ma@dalton-brothers.com"; ui.error("Something went wrong.\nPlease e-mail " + adr)


Series 60 sample screen		UIQ sample screen

`ui.fonts`

• function fonts() → Array

Gets an array with the available fonts. Each font is described by a four element array:

Index	Content	Type
0	Font name	String
1	Minimum font size in pixels	Number
2	Maximum font size in pixels	Number
3	Font is scalable	Boolean

print ui.fonts()[0] → SwissA,10,19,false

`ui.form`

• function form(items, title="mShell") → Array|null

Displays a dialog to edit the data in items, with the given title. The keys of items will be used as labels (prompts) in the form. Array elements without a key are shown as read-only texts.

The following data types can be edited:

Data Type	Field Type
String without `\n`	Single line text editor
String with `\n`	Multi-line text editor
String with trailing `ui.secret`	Password editor
Number	Number editor (floating point)
Boolean	Check box or popup yes/no choice
Array	Combo box or popup multiple choice

For the multi-line and secret editors, a terminating \n or ui.secret will be removed, so an empty multi-line field is defined by a single newline character, and an empty secret field by ui.secret.

The initial values shown in the form are the values given in items, except for an array value, where initially the first array element is selected.

If the user presses →Ok', this function returns an array with the values entered or chosen by the user. If the user presses →Cancel, null is returned.

old=["Name":"", "Details:", // just a label "Age":32, "Member":false, "Beverage":["Water", "Beer", "Wine", "Whiskey"], "Comment":"\n"]; // a multiline field new=ui.form(old, "Member Card"); print new → [Lucky Luke,35,false,Beer,He's a poor, lonesome cowboy] print keys(new) → [Name,Age,Member,Beverage,Comment]


Series 60 sample screen		UIQ sample screen

A typical username/password dialog is obtained as follows:

old=["Username":"", "Password":ui.secret]; new=ui.form(old, "Login"); print new → [lluke,rosinante]


Series 60 sample screen		UIQ sample screen

`ui.idletime`

• function idletime(reset=false) → Number

Returns the number of milliseconds since the last user activity (keypress or pointer action) on the device. If reset=true, resets the inactivity timer to zero.

// after about a minute of inactivity, beep sharp=false; while true do if ui.idletime() < 60000 then sharp=true elsif sharp then audio.beep(); sharp=false end; sleep(2000) end

`ui.keys`

• function keys(flags=0) → Number
• function keys(upAndDowns, allowFocus=false) → Number

Declares interest in keyboard events, for processing by ui.cmd. Whenever the user performs a keyboard action, the scan code or key code will be returned by the currently waiting or a next call to ui.cmd.

Sets the flags defining which keyboard events we are interested in, and returns the old flags. flags may be a bitwise combination of the following values:

• const focus = 1 If set (or if allowFocus=true), the console will obtain the keyboard focus, letting it interpret keystrokes:

On UIQ devices, the virtual keyboard will be active, and writing a character with the pen will also produce a keystroke.
On S60 devices, the keys will be interpreted as if writing a text. Keystrokes interpreted as text will be returned by ui.cmd as negative scan codes.

• const strokes = 2 If set (or if upAndDowns=false), ui.cmd will return key codes for complete keystrokes.

• const updowns = 4 If set (or if upAndDowns=true), ui.cmd will return positive scan codes for key presses and negative scan codes for key releases (each keystroke typically produces two events).

• const raw = 8 If set, keystrokes are passed to the m script before the application UI sees them. This allows to handle most application keys directly, but disables standard application behaviour, for instance the m menu (or any menu set via ui.menu), or normal text input on most devices.

• const opt1 = 16 If set, the first option key stroke (code ui.opt1key is not passed to the application UI. This allows to handle the key stroke in m, but disables the left menu on S60 devices.

• const opt2 = 32 If set, the second option key stroke (code ui.opt2key is not passed to the application UI. This allows to handle the key stroke in m, but disables the right menu on S60 devices.

Keyboard events will be ignored by ui.cmd after calling ui.keys with flags=0 (or without arguments).

Each call to ui.keys flushes the internal keyboard buffer.

The following example outputs keystrokes until the "go" key is pressed.

ui.keys(ui.strokes); // return keystrokes do c=ui.cmd(); print "pressed",c,"=",char(c) until c=ui.gokey → pressed 55 = 7 pressed 42 = * pressed 63557 =

`ui.label`

• function label(index) → String
• function label(index,text) → String

Compatibility of function `ui.label`
Sony Ericsson phones do not have option buttons to label. Setting a label with `index#0` has no effect.

With two arguments, sets the text of the title bar or option button indicated by index to text, and returns the previous setting. Passing the empty string or null as text will display the default text (e.g. the menu).

With one argument, returns the previous setting of the title bar or option button indicated by index.

Title bar or option buttons are selected according to the following table:

`index`	Meaning
0	Title bar
1	Left (first) option button
2	Right (second) option button

Setting the left option button's text overrides any menu title specified with ui.menu.

// Set the right option button text to ``Shoot'' ui.label(2, "Shoot") // Show the default button text again ui.label(2, null)

`ui.large`

• function large() → Boolean
• function large(enabled) → Boolean

Compatibility of function `ui.large`
Sony Ericsson phones	UI size change is not possible; function always returns `false`.

Without arguments, returns the current m application view size: false if the view size is small (title pane shown), true if the view size is large (title pane hidden).

With one argument, return the current view size, and sets the new view size: with enabled=true, changes the view size to large, with enabled=false, changes the view size to small. This has the same effect as toggling the view size from the menu: it changes the view size for the entire m application, in all processes.

`ui.list`

• function list(items, multiple=false, init=[], title="mShell") → Array|null

Displays a list dialog to choose from the data in items:

If multiple=false, only one item can be selected. This is usually simply the highlighted (current) item.
If multiple=true, multiple items can be selected. These are usually the marked items.

Initially, the items indexed in init will be selected (or marked).

If the user presses "ok", this function returns the indices of the items selected by the user, i.e. an array of numbers indexing into items. If the user presses "cancel", null is returned.

f=["apple.jpg", "apricot.jpg", "peach.jpg", "pear.jpg", "prune.jpg"]; print ui.list(f, true, [1,3], "Fruit Files") → [2,3]


Series 60 sample screen		UIQ sample screen

`ui.menu`

• function menu(title, commands, keepold=true, interrupt=false) → null
• function menu() → null

Replace the standard "Process" menu by a new menu, with title and the menu items defined by array commands, for processing by ui.cmd.

If keepold=true, the standard process menu will be added at the end, as a submenu. If keepold=false, the standard functions are not available, preventing the user from easily stopping or closing the running process.

If interrupt=true, a menu selection by the user will interrupt a waiting function call (except ui.cmd) with ExcInterrupted. If interrupt=false, function calls will not be interrupted, and the menu selection will go unnoticed until ui.cmd is called.

Without arguments, restores the standard menu.

Whenever the user selects a menu item, the item will be returned by the currently waiting or the next call to ui.cmd.

`ui.mfont`

• function mfont() → Array
• function mfont(font) → Array

Gets or sets the font used in all m consoles. Without parameter, returns the currently used font as an array with the following elements:

Index	Meaning	Type
0	Font name	String
1	Font size in pixels	Number
2	Bold font	Boolean
3	Italic font	Boolean

If the parameter font is a string, set the font to the one with the given name, without changing the other attributes.

If the parameter font is an array, the array must have the elements listed above, and the font is set accordingly.

old=ui.mfont(); print old → [Monospace,11,false,false] // use a proportional sans serif font ui.mfont("SwissA"); // make it large and bold ui.mfont(["SwissA", 16, true, false])

`ui.mode`

• function mode() → Number
• function mode(newmode) → Number

Compatibility of function `ui.mode`
Symbian 2nd Edition or Sony Ericsson phones	Only support mode 0.

Gets or sets the screen / user interface orientation mode.

Without an argument, returns the current mode. With a single argument, sets the mode to newmode and updates the user interface accordingly.

The following modes are available:

Value	Description
0	Unspecified: the screen mode of m follows the orientation implied by the device (e.g. flip open or closed).
1	Portrait: m is always shown in portrait mode.
2	Landscape: m is always shown in landscape mode.

Throws ExcValueOutOfRange if the desired mode is not supported.

// force mode to landscape ui.mode(2)

`ui.msg`

• function msg(message, title="mShell") → null

Displays a dialog with message, waiting until the user presses the "continue" button or a key. message can have multiple lines, separated by \n characters.

ui.msg ("This is - for a cellphone - quite a long message." + "\nIt also has a second line.", "Long message");


Series 60 sample screen		UIQ sample screen

`ui.pfonts`

• function pfonts() → null

Prints a table of the available fonts, with the following columns:

Font name.
Minimal and maximal size in pixels, separated by -.
Number of scaling steps from minimal to maximal size, prefixed by x.
Font attributes: p: proportional, s: serif, y: symbol, S: scalable.

ui.pfonts() → SwissA 10-19x4 p--- Courier 8- 8x1 -s-- Symbol 11-16x2 p-y- Calc&

`ui.ptr`

• function ptr(flags=0) → Number
• function ptr(absoluteCoord) → Number

Declares interest in pointer events, for processing by ui.cmd. Whenever the user performs a pointing device action, the pointer coordinate and button will be returned by the currently waiting or a next call to ui.cmd.

To generate these events, there must be a pointing device: on UIQ and S60 touch screen devices, the pen corresponds to button one. However, unlike a mouse, the pen only generates events while button is pressed, i.e. the pen touches the screen[9].

The function sets the flags defining which pointer events we are interested in, and returns the old flags. flags may be a bitwise combination of the following values:

• const focus = 1 If set, pointer events received will always be forwarded to the console. This allows to activate the virtual keyboard on S60 touch screen devices even if another view is shown, e.g. via graph.show.

• const relative = 2 If set (or if absoluteCoord=false), ui.cmd will return relative coordinates (the origin is the upper left corner of the console, or graph view).

• const absolute = 4 If set (or if absoluteCoord=true), ui.cmd will return absolute coordinates (the origin is the upper left corner of the screen).

Pointer events will be ignored by ui.cmd after calling ui.ptr with flags=0 (or without arguments).

The following example outputs the position of the pointing device, until the pen goes up (button one is no longer pressed) in the upper left corner of the console.

ui.ptr(ui.relative); // return relative coordinates do c=ui.cmd(); print "at",c["x"],c["y"] until c["x"]<=10 and c["y"]<=10 and c["buttons"]=0 → at 123 116 at 123 146 at 91 142 ... at 11 7 at 8 7 at 7 7

`ui.query`

• function query(prompt, title="mShell", value="") → String|Number|null

Displays a dialog querying for a single text input. The input field is initialized with value, and labelled with prompt.

If value is a number, the input field is numeric and does not allow non-numeric characters. The only valid characters are 0123456789-+,.Ee. The return value will also be numeric in this case. The function throws ExcInvalidNumber if the format of the number entered is not valid.

If the user presses "ok", this function returns the value entered by the user. If the user presses "cancel", null is returned.

The same effect can be achieved with ui.form, but ui.query is simpler to use.

old="labels.txt"; new=ui.query("New name", "Rename", old); if new#null and new#old then files.rename(old, new) end


Series 60 sample screen		UIQ sample screen

`ui.save`

• function save(path) → null
Permissions: Write(path)

Saves the current contents of the console to file path. This has the same effect as manually executing Process→Save Output, except that path is relative to the current directory of the process.

The text is written using the current source file encoding.

print "Hello world"; → Hello world ui.save("output.txt"); print io.readln(io.open("output.txt", false, io.bom)) → Hello world

`ui.text`

• function text() → Array
• function text(text) → Array
• function text(settings) → Array

Returns an array with the editable text from the console, its cursor position and the selection start position:

Index	Content	Type
0	Text	String
1	Cursor position in text	Number
2	Selection start in text	Number

With one string parameter text, also replaces the editable text by text, clears the selection and puts the cursor at the text end.

With one array parameter settings in the same format as the array returned by this function, also replaces the editable text, and sets the cursor and selection start position.

The editable text is the text which could be read from io.stdin once the user has confirmed the input. Note that console output (i.e. a print statement or output to io.stdout) freezes any preceding output text and will thus reset the editable text. These statements should therefore not be used while relying on the contents of the editable text.

Line breaks in the text are encoded by newline characters ("\n"). ui.text converts from and to platform specific line breaks as needed.

In conjunction with ui.keys allowing the focus to remain on the console editor, this function permits to produce graphical input controls via module module graph, offering the same editing capabilities (character input) as the text editor.

The following function produces a graphical element ("control") allowing the user to edit text (g is an alias for module graph):

function editLine(text, x=20, y=20, w=g.size()[0]-40) // get keystrokes, allowing the console to get focus ui.keys(false, true); // set the text, put the cursor at its end, // and select it from the beginning ui.text([text,len(text),0]); // the font height h=g.size("")[1]; do // draw the control's rectangle g.brush(g.bg()); g.rect(x, y, w, h+8); // get the current input text t=ui.text(); text=t[0]; // the cursor position in the text xc=g.size(substr(t[0], 0, t[1]))[0]; // the selection start position in the text xs=g.size(substr(t[0], 0, t[2]))[0]; // draw the selected region p=g.pen(g.cyan); g.brush(g.cyan); g.rect(x+4+xs, y+3, xc-xs, h+2); // draw the text g.pen(p); g.text(x+4, y+h+4, text); // draw the cursor g.pen(g.blue); g.rect(x+xc+3, y+4,2,h); g.pen(p); // show it all, and wait for the next keystroke g.show() until ui.cmd(500)=ui.gokey; // clear the text ui.text(""); g.hide(); return text end editLine("Lucky Luke")


Series 60 sample screen		UIQ sample screen

ui Constants

These constants define the key codes (for keystrokes) and scan codes (for key presses and releases) of the navigation keypad typically found on Nokia phones, and the Jog Dial on Sony Ericsson phones.

• const downkey = down key code The "down" navigation key.

• const downkey2 = other down key code On UIQ devices, the four way "down" navigation key; on S60 devices, same as ui.downkey.

• const downscan = down scan code The "down" navigation key scan code.

• const downscan2 = other down scan code On UIQ devices, the four way "down" navigation key scan code; on S60 devices, same as ui.downscan.

• const gokey = go key code The "go" or "confirm" navigation key.

• const goscan = go scan code The "go" or "confirm" navigation key scan code.

• const leftkey = left key code The "left" navigation key.

• const leftscan = left scan code The "left" navigation key scan code.

• const opt1key = first option key code The "first option" key (left option key on S60 devices).

• const opt1scan = first option scan code The "first option" key scan code.

• const opt2key = second option key code The "second option" key (right option key on S60 devices).

• const opt2scan = second option scan code The "second option" key scan code.

• const rightkey = right key code The "right" navigation key.

• const rightscan = right scan code The "right" navigation key scan code.

• const secret = "\u0001" The secret input field mark.

• const upkey = up key code The "up" navigation key.

• const upkey2 = other up key code On UIQ devices, the four way "up" navigation key; on S60 devices, same as ui.upkey.

• const upscan = up scan code The "up" navigation key scan code.

• const upscan2 = other up scan code On UIQ devices, the four way "up" navigation key scan code; on S60 devices, same as ui.upscan.

Next: Module vibra: Vibration Control

Navigation

m add-ons (mdoc)
Index

Manuals
[Collapse All]

Key	Meaning
`x`	x-coordinate of pointer
`y`	y-coordinate of pointer
`buttons`	mask of pressed buttons: bit 0 for button 1, bit 1 for button 2, bit 2 for button 3.

Module ui: User Interface Functions

ui.busy

ui.cmd

ui.confirm

ui.error

ui.fonts

ui.form

ui.idletime

ui.keys

ui.label

ui.large

ui.list

ui.menu

ui.mfont

ui.mode

ui.msg

ui.pfonts

ui.ptr

ui.query

ui.save

ui.text