ui.eh

Screen based user interface. More...

use "ui.eh"

Constants

const EV_HIDE = -2
const EV_ITEM = 2
const EV_ITEMSTATE = 9
const EV_KEY = 3
const EV_KEY_HOLD = 4
const EV_KEY_RELEASE = 5
const EV_MENU = 1
const EV_PTR_DRAG = 8
const EV_PTR_PRESS = 6
const EV_PTR_RELEASE = 7
const EV_SHOW = -1
const MT_BACK = 2
const MT_CANCEL = 3
const MT_EXIT = 7
const MT_HELP = 5
const MT_OK = 4
const MT_SCREEN = 1
const MT_STOP = 6

Types

type Menu < Any;
type Point < Structure;
type Screen < Any;
type UIEvent < Structure;

Functions

def Menu.get_priority(): Int;
def Menu.get_text(): String;
def Menu.new(text: String, priority: Int, mtype: Int = MT_SCREEN): Menu;
def Screen.add_menu(menu: Menu);
def Screen.get_height(): Int;
def Screen.get_title(): String;
def Screen.get_width(): Int;
def Screen.is_shown(): Bool;
def Screen.remove_menu(menu: Menu);
def Screen.set_title(title: String);
def ui_flash(millis: Int): Bool;
def ui_get_screen(): Screen;
def ui_read_event(): UIEvent;
def ui_set_app_icon(icon: Image);
def ui_set_app_title(title: String);
def ui_set_screen(scr: Screen);
def ui_vibrate(millis: Int): Bool;
def ui_wait_event(): UIEvent;

Description

Graphical application defines one or more full screen windows, in terminology of Alchemy OS called Screens. You may choose from different types of screens: Initially application has no active screen (is in console mode). Switching to graphical mode is done by calling ui_set_screen(screen). If argument is null then screen is removed from the display and application switches back to the console mode.

Screen menus

Every screen has a menu. This menu always contains item "Switch to..." which is used to switch between graphical applications. Custom menu items may be attached to a screen or detached from it anytime. Menu items are values of type Menu.

Menu item has type, label and priority. Priority determines how menus are organized. The less priority number the higher menu item will be in the menu. Menu type is a hint about intent of menu item. Depending on type platform may assign menu items to different buttons or add icons to them.

Event handling

When user interacts with the screen, application generates an UIEvent value that contains information about what happened and on which screen. These events are then read by functions ui_read_event and ui_wait_event.

ui_wait_event() will wait until something happens on the screen, and then return that event. This function is appropriate when you just passively waiting for the event.

ui_read_event() returns immediately. If there are no events, it returns null. It is appropriate for cases when you constantly need to do something (redraw screen for example).

Simple example

use "ui"
use "stdscreens"

def main(args: [String]) {
  // creating new screen
  var screen = new MsgBox("This is an example of graphical program")
  screen.title = "Example"
  // attaching menu to the screen
  var mclose = new Menu("Close", 1)
  screen.add_menu(mclose)
  // showing screen to the user
  ui_set_screen(screen)
  // waiting for Close menu
  var e = ui_wait_event()
  while (e.value != mclose) {
    e = ui_wait_event()
  }
}

Constant details

const MT_SCREEN = 1
Default menu type, with no specific intent.

const MT_BACK = 2
Menu item that returns the user to the previous screen.

const MT_CANCEL = 3
Menu item that is a standard negative answer to a dialog.

const MT_OK = 4
Menu item that is a standard positive answer to a dialog.

const MT_HELP = 5
Menu item that shows help information.

const MT_STOP = 6
Menu item that stops currently running operation.

const MT_EXIT = 7
Menu item for exiting from application.

const EV_SHOW = -1
Event of this kind is generated when screen gains focus. The field UIEvent.value is null for this kind of event.

const EV_HIDE = -2
Event of this kind is generated when screen losts focus. The field UIEvent.value is null for this kind of event.

const EV_MENU = 1
Event of this kind is generated when user chooses screen menu item. In this case the field UIEvent.value will contain chosen Menu item.

const EV_ITEM = 2
Event of this kind is generated when user activates interactive item. In this case the field UIEvent.value will contain activated Item.

const EV_KEY = 3
Event of this kind is generated by canvas on key press. The field UIEvent.value will contain Int code of pressed key.

const EV_KEY_HOLD = 4
Event of this kind is generated by canvas repeatedly if key is held down. The field UIEvent.value will contain Int code of pressed key.

const EV_KEY_RELEASE = 5
Event of this kind is generated by canvas on key release. The field UIEvent.value will contain Int code of pressed key.

const EV_PTR_PRESS = 6
Event of this kind is generated by canvas when the pointer is pressed (screen touched). In this case UIEvent.value will contain Point value with coordinates of pointer position.

const EV_PTR_RELEASE = 7
Event of this kind is generated by canvas when the pointer is released. In this case UIEvent.value will contain Point value with coordinates of pointer position.

const EV_PTR_DRAG = 8
Event of this kind is generated by canvas when the pointer is dragged. In this case UIEvent.value will contain Point value with coordinates of pointer position.

const EV_ITEMSTATE = 9
Event of this kind is generated by form when the state of an item in it changes. In this case UIEvent.value will contain Item which changed state.

Type details

type Screen < Any;
An application window which can be shown on the device display.

type Menu < Any;
Menu item that can be attached to a screen.

type UIEvent {
  kind: Int,
  source: Screen,
  value: Any
}
An event from the graphical user interface. Fields: 

type Point {
  x: Int,
  y: Int
}
2-dimensional point on the canvas. Used as return value in pointer events.

Function details

def ui_set_app_title(title: String);
Sets default title for all screens of application.

def ui_set_app_icon(icon: Image);
Sets application icon, which will appear in "Switch to..." dialog.

def ui_vibrate(millis: Int): Bool;
Requests device to vibrate for specified number of milliseconds. This function returns immediately, vibration happens in background. To stop vibrator, call this function with 0. Note, that device may limit or override duration of vibration.

Returns true if vibration is supported, false otherwise.

def ui_flash(millis: Int): Bool;
Requests device to flash backlight for specified number of milliseconds. The exact effect is device dependent, examples are are cycling the backlight on and off or from dim to bright repeatedly. This function returns immediately, flashing happens in background. To stop flashing effect, call this function with 0. Note, that device may limit or override duration of flashing.

Returns true if flashing is supported, false otherwise.

def Screen.get_height(): Int;
Returns height of the screen available to application.

def Screen.get_width(): Int;
Returns width of the screen available to application.

def Screen.get_title(): String;
Returns title of the screen.

def Screen.set_title(title: String);
Sets new title to the screen.

def Screen.is_shown(): Bool;
Returns true if this screen is shown on the phone display.

def ui_get_screen(): Screen;
Returns current screen associated with the application. If application is in console mode, this method returns null.

def ui_set_screen(scr: Screen);
Shows given screen on the display.

def Menu.new(text: String, priority: Int, mtype: Int = MT_SCREEN): Menu;
Creates new menu item that can be attached to a screen. Menu label is defined by text argument. Priority determines how menus are arranged in a list - lower number means higher priority. Menu type is one of MT_* constants defined in this header.

def Menu.get_text(): String;
Returns text label of this menu item.

def Menu.get_priority(): Int;
Returns priority of given menu item.

def Screen.add_menu(menu: Menu);
Attaches given menu item to the screen.

def Screen.remove_menu(menu: Menu);
Detaches given menu item from the screen.

def ui_read_event(): UIEvent;
Reads next event from the event queue of the application. If there are no pending events this function returns null.

def ui_wait_event(): UIEvent;
Reads next event from the event queue of the application. If there are no pending events this function waits until an event is available.