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 or when a pointer event occurs(only on touch input supported devices). 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.

Pointer events are generated by touch input supported devices. When the screen is touched the EButton1Down event is generated, EDrag while the finger/stylus is dragged across the screen and then EButton1Up when the finger/stylus is lifted.

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

For pointer events:

'type': one of the several pointer events - EButton1Up, EButton1Down, EDrag etc..
'modifiers': the modifiers that apply to this pointer event
'pos': A tuple containing the x-y pointer co-ordinates

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 methods:

bind( pointer_event, callable[, ((x1, y1), (x2, y2))])

This method can be used to listen to specific pointer events. The pointer_event argument can be any one of the pointer events listed in the key_codes module.

The most common pointer events are:

EButton1Down - Pen down event
EButton1Up - Pen up event
EDrag - Drag event (This event is only received when button1 is down)
ESwitchOn - Switch on event caused by a screen tap.

callable is called when the pointer_event and the co-ordinate (if specified) criterion matches.

((x1, y1), (x2, y2)) is an optional argument that can be passed to specify the screen area to monitor for any specific pointer event. The two co-ordinate tuple corresponds to the top-left and bottom-right points. This argument will be ignored if the event is not a pointer event.

There are several ways in which bind can be used:

my_canv.bind(EButton1Up, callback) - The callback is called when EButton1Up event is generated anywhere in the canvas.
my_canv.bind(EButton1Up, green_callback, ((x1, y1), (x2, y2))) - The callback is called when the EButton1Up pointer event occurs inside the screen area specified.
my_canv.bind(EButton1Up, yellow_callback, ((x3, y3), (x4, y4))) - Registers another callback for a different region but for the same pointer event. When two screen areas overlap, the callback registered last will be called when pointer events occur in the intersected region.
my_canv.bind(EButton1Up, callback3, ((x1, y1), (x2, y2))) - If the pointer event and the screen area to be monitored are the same, the callback passed will replace the old callback already registered.
my_canv.bind(EButton1Up, None, ((x1, y1), (x2, y2))) - If the pointer event and the screen area to be monitored are the same, and the callback passed is None, the callback registered previously is cleared.
my_canv.bind(EButton1Up, None) - All callbacks previously registered for this pointer event are cleared, regardless of whether it was for a specific screen area or for the entire canvas.

**Figure 3.8:** Canvas bind scenarios
$\includegraphics[width=5in]{bind-scenarios}$

Clicking on the white spot should result in green_callback to be called. Clicking on the red spot should result in yellow_callback to be called in both the scenarios shown above provided the yellow_callback was registered last. Clicking on the purple spot should result in yellow_callback to be called.

begin_redraw( [((x1, y1), (x2, y2))])

This is an explicit function that can be used to signal the window server that "I'm about to redraw this area". This method tells the window server that the window is about to respond to the last redraw event by redrawing the specified rectangle. This causes the window server to clear the rectangle, and remove it from the invalid region. The optional co-ordinates x1, y1, x2, y2 should be the rectangle that has to be marked for redrawing.

After the redraw is complete the application should call end_redraw().

Note: The begin_redraw and end_redraw methods should not be called inside the redraw callback function.

Couple of FAQs on redraw/non-redraw drawing:

Question: What is non-redraw drawing?

"Non-redraw drawing" is any canvas/graphics drawing operation performed outside of begin_redraw()/end_redraw().

Question: What should applications do instead of non-redraw drawing?

"Redraw drawing" is any drawing delimited by begin_redraw()/end_redraw().

Question: Why is non-redraw drawing bad for performance?

The window server caches drawing operations in the redraw store. Delimiting drawing with begin_redraw()/end_redraw() allows window server to efficiently manage drawing operations.
If applications perform drawing operations outside begin_redraw/end_redraw, window server cannot cull drawing operations from its cache of drawing operations, because it cannot know whether a set of drawing operations has been superceded by a new set. In this scenario every frame of drawing that is done on a non-redraw drawing window will become slower and slower as it draws all the drawing operations for the entire history of the window (well actually up until the last begin_redraw/end_redraw for the whole window).
If an application performs begin_redraw/end_redraw, it tells the window server that it can throw away any old drawing operations it had for the area of the window specified in the redraw, thus allowing for more optimal management of drawing operations.

Question: What are the changes required for redraw drawing?

Applications should delimit their drawing with begin_redraw()/end_redraw() - i.e. they should replace non-redraw drawing with redraw drawing. Sometimes, this is as straight forward as adding these calls to existing rendering code. In other cases (where the application has been drawing using "incremental updates" to the window, the application drawing code would need to be reworked to perform a full refresh of the area redrawn for the rect provided in begin_redraw(rect).

end_redraw( ): Ends the current redraw. This function should be called when redrawing is complete.

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.