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:

For pointer events:

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:

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

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:

Figure 3.8: Canvas 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?

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

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

Question: What are the changes required for redraw drawing?

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

Instances of Canvas type have the following attribute:

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.