Re: [java-gnome-hackers] Layout size related methods

[Owen T. <ot...@re...>]

On Wed, 2008-09-17 at 00:15 +1000, Andrew Cowie wrote:
> Vreixo,
> 
> I've been working on the 'pango' branch. I'd like to include it in 4.0.9
> as it nicely complements the 'textview' work.
> 
> I'm a bit concerned about the size related methods in Layout. I've taken
> an number of different cracks at it, and now I've got it to:
> 
>         getSizeWidth()
>         getSizeHeight()
> 
> and
> 
>         getPixelWidth()
>         getPixelHeight()
> 
> which seems to be a fairly decent stab at regularizing the completion
> space. Still, I'm not 100% about it.
> 
> Part of my doubt is that now that we've got these normalized, these
> methods now seem to return the same thing - just the sort of thing to
> make me somewhat unconvinced that we actually need both pairs. That
> said, it is probably best we leave both sets there - there is return
> type to be considered.
>
> The real issue, of course, is *explaining* what the difference is, and
> that's where I got a bit vague. I have a hunch that it is the whole
> points vs device units vs pixels thing that I'm getting confused by.

Without looking at your code, it's hard for me to say where you are
getting confused. Some points that may be helpful.

 * All functions to get size and metrics in Pango work in the same 
   coordinate space. This coordinate space is  equivalent to the cairo
   user space. If you haven't made any transformations, then this
   coordinate space has units of pixels.

 * Lengths are usually in fixed point 22.10 format. (Called "pango
   units.) In C, you interconvert

    pixel_length = PANGO_PIXELS(length) // also PANGO_PIXELS_FLOOR/CEIL
    length = pixel_length * PANGO_SCALE

 * It's a frequent operation to want extents *in integer pixels*;
   doing the rounding properly round a fixed point rectangle to the
   small enclosing integer pixels is slightly tricky, and something
   you commonly want todo so there are functions like
   pango_extents_to_pixels() pango_layout_get_pixel_extents()
   pango_layout_get_pixel_size()

   E.g., if you have a rectangle with x = 0.9 width = 5.2, the pixel
   width is not 5 (rounded) or 6 (ceiling), it's 7.

How does this map to Java? It's partly a question about how much you are
deviating from the Pango API. If you want to stick close, all you need
is break get_extents() into:

  Rectangle getInkRectangle()
  Rectangle getLogicalRectangle()

And on Rectangle have:

  Rectangle toPixels()
  int getX()/getY()/getWidth()/getHeight()

That's complete in terms of mapping all of 
pango_layout_get_[size/pixel_size/extents/pixel_extents]. Beyond that, 
you might want to add for layout:

 getPixelWidth()/getPixelHeight()

As convenience functions. I'm not sure that getSizeWidth()/getSizeHeight() 
are necessary. Ugly names...

- Owen