The best description on the use of the canvas is on the MeBox project page: http://urandom.ca/mebox/canvas/. This description is slightly outdated, but will give you a clear idea of what the Canvas is about, and some of the possibilities it has.
kaa.canvas is a replacement (a newer and better version) of Mevas.
The canvas has two jobs. One is to define and layout objects, the other is to render them for display. Objects can be anything from text to movies playing in-canvas, for the moment the source-code (together with the link mentioned above) is the best way to gaining an understanding on how they work and how to use them. The sourcecode is divided into two parts too, the kaa.canvas directory contains the canvas-objects, the kaa.canvas.displays directory contains the "connectors" to the the displays from kaa.display. In addition a Buffer display is defined, which can be used to read out the rendered canvas data to be used in other projects.
The canvas relies (only for the rendering, but a canvas without rendering doesn't seem very useful) on the evas-library, and the kaa.evas bindings hereto. The exact architecture is was explained to me in a PM from Jason Tackaberry:
The doc on my site [the link to the MeBox page mentioned above] is somewhat outdated (although still relevant). Eventually it will be moved into kaa.canvas svn and put on the Kaa site. That's put on hold because right now I have gutted kaa.canvas and it's on my plate to do nearly a complete rewrite (at least of the layout engine) as the current code is intractable (both in readability and in performance).
kaa.canvas does rendering through kaa.evas, though kaa.canvas does provide a whole lot of higher level functionality and abstraction on top of evas (that includes a layout model). Evas is responsible for blitting to the appropriate buffers and updating the views relevant for the given display (be it X11, directfb, fb, whatever). kaa.display's purpose is to provide a simple API to interface with a given display (X11, directfb). It also acts as a glue between the display and Evas.
For example, you'd use kaa.display to create an X11 window, specify its size, title, etc. This would provide an X11Window object, and you can use its methods to manipulate that window: resize it, hide/show it, toggle fullscreen, etc. Evas does not concern itself with this stuff, so we need a separate API for this. All Evas wants to know is the X11 Window id it's supposed to draw to. kaa.evas itself doesn't know about X11 either. So kaa.display exists to provide an API for accessing the display, and to talk to kaa.evas to create the appropriate Evas objects.
A lame attempt at a diagram:
+-----------------------------------+
| Application |
+-----------------------------------+
| | kaa.canvas |
| +------------+------------------+
| kaa.display <-|-> kaa.evas |
+----------------+------------------+
| actual display (X11, dfb) |
+-----------------------------------+What this says is the Application talks mainly to kaa.canvas, although it may use a small part of kaa.display's API directly (it will fetch the appropriate kaa.display object from the canvas and then call certain methods on it directly, such as resizing or toggling fullscreen). kaa.canvas uses both kaa.display and kaa.evas, both of which fully abstract the underlying display (X11, dfb, etc.) kaa.display works with kaa.evas to glue Evas to the display requested by the user.
(Obviously the app will also use several other modules, including modules from kaa, but this diagram is just from the display perspective).
Triggering and catching triggers
The canvas is triggered by the main loop (see SourceDoc/KaaNotifier) by connecting its render method to the "step" signal. Kaa.canvas defines two signals itself, "key_press_event" and "updated". The "updated" event fires whenever the canvas has been updated and has been through its render-routine. Methods connected to this signal should expect a parameter, being the rectangle that has been updated.