goocanvas notes

[Havoc Pennington <hp redhat com>]

Hi,

I read over the GooCanvas code and wrote down everything I thought of, 
some of it is half-baked or quarter-baked, but hopefully helpful in some 
way.

Havoc

- GooCanvas object could have private fields, also e.g ItemSimple has 
public fields... I think it's nicer to always use accessors, they have 
to be written for language binding use anyway

- set_bounds() seems to imply the bounds of the whole canvas can't just 
be "the bounds of all the contained items" - suggest that the bounds are 
always the contained items, but that there's a "clip" or "viewport" item 
available that has a fixed size and clips its child items

- the "protected" functions on GooCanvas seem to imply that items have 
to know about their containing canvas widget. This creates a pretty 
tight linkage to the widget and makes it easier to write items that 
can't be printed or can't be rendered elsewhere; I kind of like the 
CanvasContext/CanvasContainer abstraction in HippoCanvas for this reason

- it seems a little clunky that CanvasItem(Model) has optional 
interfaces embedded in it (container, transformable, stylable) - this 
will map poorly to languages such as Java.

- in HippoCanvas I'm experimenting with avoiding the visibility flag 
(which in GTK gets checked all over the place) and instead just allow 
0x0 items (hidden) or items that choose not to draw (invisible). This 
makes hidden items "just work" In a lot of cases. (I guess more 
accurately, HippoCanvas moves the visibility flag to the container, so 
item implementations don't have to check it. The downside of this is 
that you can't set visibility on an item when it's outside of a container.)

- in terms of naming, since invisible in GTK is hidden in GooCanvas, and 
CSS has its names here that I forget, perhaps better names would be more 
explicit like ZERO_SIZE and NOT_DRAWN (or something)

- PathCommand seems worth making opaque
- LineDash also

- the need to register all the cairo types is a pain :-/ every lib is 
having to do this. Not worth a "glib-cairo" lib though...

- I wonder if CanvasItemSimple would benefit from being broken up. The 
two main subclasses I would envision:
  - Shape - would include fill, stroke style,  pointer events, etc. and 
be the parent class for often-nonrectangular items that draw a shape. 
Seems to me a number of these props don't make sense on non-Shape type 
of items, such as buttons or text entries or even Image. But on the 
other hand, having the same GooCanvasStyle cascade through all items is 
useful, so hmm.
  - Control - always rectangular, would add properties similar to 
HippoCanvasBox in particular padding, border, xalign, yalign (I guess 
these are child props on table right now... maybe that is better indeed).

- breaking up ItemSimple may relate to also splitting up 
CanvasItem(Model) interfaces?

- AbstractItem is a clearer name than ItemSimple maybe

- HippoCanvasBox has an "if fits" flag, which is sort of like shrink but 
is all-or-nothing (i.e. the child gets its min size or gets no size). 
The rationale is that getting half your min size is often not useful

- the min size vs. natural size distinction would be very useful 
(another aspect of this is calling it "min size" instead of "request" - 
less confusing imo, the request should be the combo of both min and 
natural, rather than being the min as in gtk)

- it's a little strange to me to have 
get_requested_area/get_requested_height rather than 
get_requested_width/get_requested_height - then implement get_area by 
just calling width then height

- should RectData (and similar such as ImageData) be in the public API?

- the x,y prop e.g. on CanvasText seems like it should be a child 
property in Group rather than a property of the item ?

- the width prop on CanvasText seems like it should just set the natural 
width in the width request, and then the text item would actually _draw_ 
to its allocation, whatever the allocation ends up being; this means 
maybe this prop belongs on a base class or interface for any item, since 
it's just controlling the width request and nothing text-specific. In 
fact maybe the prop should be called min-width and there should also be 
natural-width, but no plain "width" since it's unclear which width that 
would be.

- I have mixed feelings on the thing where the model is optional and you 
can just use views directly ... it allows skipping the model-view 
complexity in using the canvas if you want, but then it seems to 
complicate the canvas item implementations

- get_requested_area would be nicer if items could return their bounds 
in their own coordinates - in general I think it's nicer if items only 
ever see item coordinates, there is no reason they need to know about 
any other coordinates unless they "break the abstraction" and know about 
the GdkWindow they are drawing to for some reason (such as doing GDK 
calls). Certainly coordinate conversions were confusing and messy in 
GnomeCanvas, GooCanvas cleans up most of it but it looks like 
get_requested_area remains

- simple_paint() takes a "bounds" arg but e.g. polyline and text don't 
do anything with it; is this needed? (if it's a clip, couldn't the 
parent just clip the cairo_t?)

- get_requested_area() takes a cairo_t, I wonder if it should take a 
more general "context" object that could contain e.g. the theme or the 
theme's font - this would allow having stuff like two views with 
different themes or something. HippoCanvas uses a set_context() instead 
of passing it to the request methods, but this results in a need to 
globally set_context() to say a printer context, call methods, and set 
context back, or something like that, which is a little ugly.

- I think the enter/leave/motion model from GDK/GTK is pretty annoying, 
it might be worth cleaning up (e.g. just have one event for 
motion/enter/leave, tag the first motion with an enter flag, last motion 
with a leave flag, guarantee enter-leave pairing even if the item gets 
destroyed, and track a "hovering"/contains-pointer flag... stuff like 
that. details tbd ;-)

- it's kind of gross to have GdkEvent used in the Item interface because 
it ties to the Item interface to X in effect.  on the other hand, it's 
pretty ugly to invent a new system too. One thing that's confusing about 
it is that having the x,y in the event be in GdkWindow or item
coordinates are both reasonable guesses, and either way is confusing 
sometimes.

- certain common "event handling patterns" are nice to provide 
convenience functionality for: prelight on hover; double click to 
activate; drag with left mouse

- in the http://svn.mugshot.org/dumbhippo/trunk/client/canvas/TODO I 
have a little note about knowing the return value (bubbling) of a button 
press handler known in advance; this allows "composite items" that still 
do the right thing wrt prelight and double-click-to-activate. Not sure 
exactly how it would work, but it would be nice to be able to build say 
a container with an image and a text, and then treat it as a clickable 
unit trivially
- this also relates to tooltips behavior

- having x,y,width,height on canvas widget seems odd ... again x,y seem 
like they are properties of a GtkFixed/GooCanvasGroup type of container, 
and width/height seem redundant with size request so should be generic 
to all items

- right now Table derives from Group and then there are some container 
methods in Item... maybe nicer would be an interface Container, perhaps 
an AbstractContainer with some common implementation, then deriving from 
that have Table and Group/Fixed as two separate ones - this probably 
makes more sense if x,y are moved from individual items and become child 
props of Group/Fixed

- as a general theme I wonder if the memory size of items can be 
reduced... in particular it's easy to have a whole lot of Table (or a 
lighter Box?), Text, and Image items so those are good to have as small 
as possible if there are some good wins available

- I think GtkMisc having xalign/yalign as a double is sort of dumb; in 
HippoCanvasBox I changed it to an enum fill/start/center/end which 
results in more readable application code and a clearer API. I have 
_never_ seen anyone use anything but 0.0, 0.5, and 1.0 as values here. 
And adding "fill" as one of the values is also handy. Anyhow not sure I 
would have the Table item copy GtkMisc in this oddity.

- I'm not groking the memory management on items - shouldn't there be a 
sink(), or use GInitiallyUnowned? I am probably missing something

- I think a Link/URL item, and/or enabling urls in the markup in the 
Text item, would be extremely useful

- a gradient item would be handy

- background and border color props would be handy - this is perhaps one 
argument for putting border in the items, instead of child props in the 
table, though I guess the border color could be a child prop too

- an "image button" item would be handy (make a button from a set of 
images representing the button states)

- supporting prelighting on the Image item might be nice too, either as 
a transform (lighten the pixels) or by setting a second image

- I think it would be good to write some more "widget toolkit" type of 
demos (with buttons, entries, lots of text items... try to copy some 
real-world apps perhaps) and look for places where things aren't as 
convenient as GTK, Qt, or HippoCanvas - just to be sure the canvas is 
crisp and nice for both the GnomeCanvas style uses and the 
widget-layout/html-like uses

- a markup for building trees of items would certainly be handy, just as 
glade is handy