ui.eh

Screen based user interface. More...

use "ui.eh"

Constants

const EV_HIDE = -2
const EV_ITEM = 2
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

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 new_menu(text: String, priority: Int): 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.

New menu is created with constructor new_menu(label, priority). Priority determines how menus are organized. The less priority number the higher menu item will be in the menu.

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", null)
  screen.set_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 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.

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 new_menu(text: String, priority: Int): 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.

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.