canvas.eh

Screen on which you can do arbitrary drawing. More...

use "canvas.eh"

Constants

const ACT_A = 9
const ACT_B = 10
const ACT_C = 11
const ACT_D = 12
const DOWN = 6
const FIRE = 8
const KEY_0 = '0'
const KEY_1 = '1'
const KEY_2 = '2'
const KEY_3 = '3'
const KEY_4 = '4'
const KEY_5 = '5'
const KEY_6 = '6'
const KEY_7 = '7'
const KEY_8 = '8'
const KEY_9 = '9'
const KEY_HASH = '#'
const KEY_STAR = '*'
const LEFT = 2
const RIGHT = 5
const UP = 1

Types

type Canvas < Screen;

Functions

def Canvas.action_code(key: Int): Int;
def Canvas.graphics(): Graphics;
def Canvas.has_hold_event(): Bool;
def Canvas.has_ptr_events(): Bool;
def Canvas.has_ptrdrag_event(): Bool;
def Canvas.new(full: Bool = false): Canvas;
def Canvas.read_key(): Int;
def Canvas.refresh();

Description

This header provides a Screen called "canvas". Canvas provides facilities of low-level drawing on the display and allows to read key presses and touch events. Canvas is double-buffered, all drawings are performed on off-screen buffer that is obtained with Canvas.graphics. After drawing is finished, Canvas.refresh should be called to present changes on the display.

Key events

If you press the key while the active screen is canvas, the UIEvent will be generated. Its kind field will be EV_KEY and its value field will contain the code of the pressed key. Since returned type of the UIEvent.value is not known at the time of compilation, you have to cast it manually 
// read the next event
var e = ui_wait_event()
if (e.kind == EV_KEY) {
  // obtain key code
  var key = e.value.cast(Int)
  // if it is a character, print it in the terminal
  if (key > 0) {
    write(key)
  }
}
Similarly, when key is released, EV_KEY_RELEASE event is generated. Also, if key is held down, device may generate EV_KEY_HOLD event repeatedly. The last event type is optional, to test if device supports hold events, use Canvas.has_hold_event.

This header defines key codes for standard phone keypad (keys 0..9, * and #). If the phone has other alphanumeric keys, the code (most probably) will be the corresponding Unicode character code. If phone has non-alphanumeric keys (for example, joystick), those keys will (most probably) return negative key codes. However, actual key codes may be different on distinct hardware. If you want your application to be portable, you should use only the standard key codes provided by this header. Or use the action codes.

Action codes

Since keypads differ from device to device, platform provides the following portable action codes: UP, DOWN, LEFT, RIGHT, FIRE, ACT_A, ACT_B, ACT_C and ACT_D. Each key code is mapped to at most one action code. However, multiple keys may be mapped to the same action code. For example, if the phone has joystick, both moving the joystick up and pressing '2' key will generate UP action. To get action code for the pressed key use Canvas.action_code(key).

Pointer events

If device has touch screen, the canvas may generate pointer events. To test whether the device supports touch events, use Canvas.has_ptr_events and Canvas.has_ptrdrag_event. For pointer events value field of the event will be of type Point. Since compiler cannot predict type of the value, you have to cast it to the needed type manually to extract values x and y. 
var e = ui_wait_event()
if (e.kind == EV_PTR_PRESS) {
  var p = e.value.cast(Point)
  do_something_at(p.x, p.y)
}

Constant details

const KEY_0 = '0'
Key code for key 0.

const KEY_1 = '1'
Key code for key 1.

const KEY_2 = '2'
Key code for key 2.

const KEY_3 = '3'
Key code for key 3.

const KEY_4 = '4'
Key code for key 4.

const KEY_5 = '5'
Key code for key 5.

const KEY_6 = '6'
Key code for key 6.

const KEY_7 = '7'
Key code for key 7.

const KEY_8 = '8'
Key code for key 8.

const KEY_9 = '9'
Key code for key 9.

const KEY_STAR = '*'
Key code for key *.

const KEY_HASH = '#'
Key code for key #.

const UP = 1
Constant for the UP action.

const DOWN = 6
Constant for the DOWN action.

const LEFT = 2
Constant for the LEFT action.

const RIGHT = 5
Constant for the RIGHT action.

const FIRE = 8
Constant for the FIRE action.

const ACT_A = 9
Constant for the general purpose "A" action.

const ACT_B = 10
Constant for the general purpose "B" action.

const ACT_C = 11
Constant for the general purpose "C" action.

const ACT_D = 12
Constant for the general purpose "D" action.

Type details

type Canvas < Screen;
Screen for low-level drawing.

Function details

def Canvas.new(full: Bool = false): Canvas;
Creates new canvas screen. If fullscreen is true then created canvas is in fullscreen mode.

def Canvas.graphics(): Graphics;
Returns the graphical buffer for this canvas on which you can draw.

def Canvas.read_key(): Int;
Returns key code of the last pressed key. If no key was pressed, returns 0. This is convenient function, if you want to receive only key presses from canvas. If you want to receive other kinds of events, use event framework.

def Canvas.refresh();
Refreshes displayed content of the canvas.

def Canvas.action_code(key: Int): Int;
Returns the action code for the specified key code. If given key has no associated action, then 0 is returned.

def Canvas.has_ptr_events(): Bool;
Checks if the platform supports pointer press and release events. If returns true, the canvas will generate EV_PTR_PRESS and EV_PTR_RELEASE events.

def Canvas.has_ptrdrag_event(): Bool;
Checks if the platform supports pointer dragging events. If returns true, the canvas will generate EV_PTR_DRAG event.

def Canvas.has_hold_event(): Bool;
Checks if the platform supports key hold event. If returns true, the canvas will generate EV_KEY_HOLD event.