API Review RT:17407 Canvas Node

[Jim Graham]

Hi Tom,

On 4/20/12 3:24 AM, Tom Schindl wrote:
> Hi Jim,
>
> Another thing I'm not sure about is how I get informed e.g. that I
> should redraw. Do I have to react on Size-Changes, ... myself or would I
> get a callback, to do so?

There are no callbacks and size changes currently only happen because 
you called one of the methods that changed its size.  Nothing in FX will 
change its size on you for you to react to - only you would do that. 
You just create it, render to it immediately, then it lives forever with 
that rendering until you decide to change its size or render more, or 
erase it and start over.

That's the current design modeled after HTML5 Canvas, but other parts of 
this discussion are focusing on whether this is the right design.

> This leads to the next question: Let's say I have a Canvas who has a
> size of 1000x1000 but only a rect of 0/0/100/100 is visible can I
> somehow find out this and only draw the content in this area and
> possible get a callback when the visible area changes?

No, the entire area must be available for rendering because you will 
render it and then we will show it for you regardless of how much is 
visible right now, or in the future.  It's a "captured rendering", not a 
"surface to respond to damage events on".

> So an API like this would be a really cool thing to have:
>
> ---------8<---------
> Canvas#setPaintContextCallback(Callback<PaintContext>  callback);
>
> PaintContext {
>    private Rectangle bounds;
>    private GraphicsContext context;
> }
> ---------8<---------
>
> Maybe such an API could be added later on?

If we add it later then we risk introducing a need for it and initial 
usages will not be prepared to deal with the damage.  The design should 
really be one or the other, not "static, but with an optional callback". 
  Though, if we did add a callback later then I imagine we could spec it 
such that it is null by default and when it is null then we retain for 
you and only when you add a callback do we switch to a damage model. 
But, it would be hard to add "manageable" on the fly dependent on that 
callback and that is the primary model that people would want the 
callbacks for.

I think I'd see making an alternate "ManagedCanvas" type class, but I'll 
go over that in a separate email.

> Should there be a short circuite method to clear the complete drawing if
> I get the API correct I currently have to call clearRect().

Yes, clearRect() is how you clear the current canvas.

> Am 20.04.12 02:09, schrieb Jim Graham:
>> Canvas.getGC() only keeps one instance and keeps returning it - good/bad?
>
> What happens if I fetch to 2 GCs - are both valid to draw in the canvas
> at the same time? If it returns a new one everytime createGC() is
> probably the right for it name. I don't feel very strong about that.

The name is getGC because it returns the same one every time.  There is 
only a singleton instance ever so there is no "both" that would need to 
be "both" valid.  "It" is valid and everyone gets and uses the "it".

>> Constructing a path in the GC vs. separate Path object?
>
> I would vote for GC.createPath() and move the Path API to it which would
> make the GC-API smaller and would align with the createImageData API.

That's an interesting alternative to "new Path2D()".

>> drawFoo() vs. strokeFoo() for drawing the outline of something?
>
> I don't fully understand why there is strokeRect() what is it good for?

Drawing the outline/border of a rectangle.

> You currently have:
> * drawRoundRect
> * strokeRect

We plan to standardize on "strokeFoo" for all of the methods that draw 
the outline/border of something.

> a) Shouldn't you use Rectangle?

The Node?  We don't want to involve Node objects in the rendering 
interface (though we use some of the same simple enums/objects they use 
for their attributes).

> b) I would vote for drawRectangle which BTW is nothing more than
>     calling drawRoundRectangle with 0 as the arcs right?

Arguably yes, but it's such a simple addition and reads more directly 
than having to look at the arguments and see if there are two 0's in 
there, so I think we'll keep the distinction.  Note that the Rectangle 
node has optionally rounded corners, but they are separate properties so 
they don't appear every time you interact with it and force you to type 
", 0, 0" to ignore them...

			...jim