3.1.10 Canvas Type

Canvas is a UI control that provides a drawable area on the screen and support for handling raw key events. Canvas supports the standard drawing methods that are documented in Section 3.3.

class Canvas( [redraw_callback=None, event_callback=None, resize_callback=None])

Constructs a Canvas. The optional parameters are callbacks that are called when specific events occur.

Note: Watch out for cyclic references here. For example, if the callbacks are methods of an object that holds a reference to the Canvas, a reference cycle is formed that must be broken at cleanup time or the Canvas will not be freed.

redraw_callback is called whenever a part of the Canvas has been obscured by something, is then revealed, and needs to be redrawn. This can typically happen, for example, when the user switches away from the Python application and back again, or after displaying a pop-up menu. The callback takes as its argument a four-element tuple that contains the top-left and the bottom-right corner of the area that needs to be redrawn. In many cases redrawing the whole Canvas is a reasonable option.

event_callback is called whenever a raw key event is received. There are three kinds of key events: EEventKeyDown, EEventKey, and EEventKeyUp. When a user presses a key down, events EEventKeyDown and EEventKey are generated. When the key is released, an EEventKeyUp event is generated.

The argument to the event_callback is a dictionary that contains the following data for key events:

'type': one of EEventKeyDown, EEventKey, or EEventKeyUp
'keycode': the keycode of the key
'scancode': the scancode of the key
'modifiers': the modifiers that apply to this key event

Each key on the keyboard has one or more scancodes and zero or more keycodes associated with it. A scancode represents the physical key itself and a keycode is the result of state-related operating system defined processing done on the key. For keys that correspond to a symbol in the current character set of the phone, the keycode is equal to the code of the corresponding symbol in that character set. For example, if you are using the Nokia Wireless Keyboard (SU-8W), pressing the key A will always produce the scancode 65 (ASCII code for an upper case A), but the keycode could be either 65 or 91 (ASCII code for a lower case A) depending on whether or not the Shift key is pressed or Caps Lock is active.

The key_codes module contains definitions for the keycodes and scancodes. See Figure 3.7 for the codes of the most common keys on the phone keypad.

Some keys are handled in a special way:

A short press of the Edit key causes it to stay down, meaning that no EEventKeyUp event is sent. The event is only sent after a long press.
Detecting presses of the Voice tags key or the Power key is not supported.
If the right softkey is pressed, the appuifw.app.exit_key_handler callback is always executed.

There is no way to prevent the standard action of the Hang-up key, the Menu key, the Power key or the Voice tags key from taking place.

Figure 3.7: Keycodes and scancodes for phone keys usable from Python applications

$\includegraphics[width=5in]{6630keyboard}$

Key	Keycode	Scancode
1.	EKeyLeftSoftkey	EScancodeLeftSoftkey
2.	EKeyYes	EScancodeYes
3.	EKeyMenu	EScancodeMenu
4.	EKey0...9	EScancode0...9
5.	EKeyStar	EScancodeStar
6.	EKeyLeftArrow	EScancodeLeftArrow
7.	EKeyUpArrow	EScancodeUpArrow
8.	EKeySelect	EScancodeSelect
9.	EKeyRightArrow	EScancodeRightArrow
10.	EKeyDownArrow	EScancodeDownArrow
11.	EKeyRightSoftkey	EScancodeRightSoftkey
12.	EKeyNo	EScancodeNo
13.	EKeyBackspace	EScancodeBackspace
14.	EKeyEdit	EScancodeEdit
15.	EKeyHash	EScancodeHash

resize_callback is called when screen size is changed when the Canvas rect size has been changed. The callback takes as its argument a two-element tuple that contains the new clientRect width and height.

Instances of Canvas type have the following attribute:

size: A two-element tuple that contains the current width and height of the Canvas as integers.

Instances of Canvas type have the same standard drawing methods that are documented in Section 3.3.

See About this document... for information on suggesting changes.