|[redraw_callback=None, event_callback=None, resize_callback=None])|
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:
EEventKeyUp. When a user presses a key
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
'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 -
'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:
EEventKeyUpevent is sent. The event is only sent after a long press.
appuifw.app.exit_key_handlercallback 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.
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:
|pointer_event, callable[, ((x1, y1), (x2, y2))])|
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.
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.
|[((x1, y1), (x2, y2))])|
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?
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?
Instances of Canvas type have the following attribute:
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.