2007-06-10  Behdad Esfahbod  <behdad@gnome.org>

        Bug 347236 – provide pango_cairo_font_get_scaled_font

        * pango/pangocairo-font.c: New public API:
        
                pango_cairo_font_get_scaled_font()

        * pango/pangocairo-fontmap.c: New public API:
        
                pango_cairo_font_map_new_for_font_type()
                pango_cairo_font_map_get_font_type()

        * pango/pangocairo-fcfontmap.c:
        Implement get_font_type() method.

        * pango/pangocairo.h:
        * pango/pangocairo-private.h:
        * docs/pango-sections.txt:
        * docs/tmpl/pangocairo.sgml:
        * pango/pangocairo.def:
        Update.

I'm not sure how to deal with this new method for the Perl bindings.

pango_cairo_font_get_scaled_font resides in the pango_cairo_font_ namespace, but takes an instance of type PangoFont.  Judging from the docs and the code, pango_cairo_font_get_scaled_font can legally be called only on a special subset of instances of type PangoFont: the docs say "@font: a #PangoFont from a #PangoCairoFontMap".  As far as I can see, this kind of information isn't available at compile time.

So how do I wrap it?  Bind pango_cairo_font_get_scaled_font as if it were named pango_font_get_scaled_font, i.e. make it callable on every PangoFont instance: $font->get_scaled_font()?  Or wrap it as a helper function: Gtk2::Pango::Cairo::Font::get_scaled_font($font)?

I don't really like the first option, since it shifts the burden of checking for correctness to the programmer who would have to decide whether it's legal to call get_scaled_font() on the particular instance he has in hands.  It also pollutes a foreign namespace which can lead to name clashes.  The second option is ugly and makes pango_cairo_font_get_scaled_font look like a helper function whereas it really is more of a method.

(All this might sound like I'm asking you to do my job, but I think other bindings will have similar problems.)

IMO (I'm not the maintainer) it's weird this was added as a PangoFont method 
without exposing the PangoCairoFont interface type. There may be internal
gymnastics related to avoiding cut-and-paste code, but the external
view should be that some fonts implement an interface with additional
methods (the vtable for the iface doesn't need to be exposed, just the
type for the iface)

I was trying to follow the pattern that was already there, that:

void pango_cairo_show_glyph_string (cairo_t          *cr,
                                    PangoFont        *font,
                                    PangoGlyphString *glyphs);


takes a PangoFont, not a PangoCairoFont.  It's not just here, the confusion is all over Pango.  For example see pangoxft.h:

XftFont *     pango_xft_font_get_font          (PangoFont *font);
Display *     pango_xft_font_get_display       (PangoFont *font);
#ifndef PANGO_DISABLE_DEPRECATED
FT_Face       pango_xft_font_lock_face         (PangoFont *font);
void          pango_xft_font_unlock_face       (PangoFont *font);
guint         pango_xft_font_get_glyph         (PangoFont *font,
                                                gunichar   wc);
gboolean      pango_xft_font_has_char          (PangoFont *font,
                                                gunichar   wc);
PangoGlyph    pango_xft_font_get_unknown_glyph (PangoFont *font,
                                                gunichar   wc);

And I know this has created lots of headaches for binding people before.  Another similar thing is that even the pangocairo fontmap constructors return PangoFontMap.  That's slightly different though.  So, what is the preferred pattern?

Since pango_cairo_show_glyph_string is a helper function, it's wrapped accordingly in the Perl bindings:

  Gtk2::Pango::Cairo::show_glyph_string($cr, $font, $glyphs);

So the type of the font isn't that much of a problem in this case.  It's different for pango_cairo_font_get_scaled_font.  This one really is a method working on the font, and you'd like to be able to say

  $font->get_scaled_font

For this, the type of the font is crucial.

I can't say much about API naming patterns in pango or whether legacy API should influence new API.  But from a binding's perspective, there's one clear rule: a method's prefix must agree with the type of the instance it gets passed.  Otherwise it's hard to wrap.

How do you handle the Xft ones I listed?

I don't think you can extra a *lot* of sense from old stuff in Pango
like the Xft API... the functions may have been added at a point I
didn't want to expose PangoXftFont or something.

I think pango_cairo_show_glyph_string() mostly has the PangoFont parameter
because it matches the generic pango_renderer_draw_glyphs(). (*)

What I'm really campaigning for with PangoCairoFont is not so much
changing the type of the parameter (though I think you should, and I
believe recent Pango fnuctions are pretty clean about it), but rather
exposing enough .. the get_type() function, in particular, so that 
language bindings can deploy their standard methods for binding
an interface and put the PangoCairoFont method(s) on that interface.

[ now, the challenge for language bindings is that PangoCairoWin32Font
FcFont aren't public, and shouldn't be public, so it's not clear 
what type the proxy object should have ... probably the language binding
needs to have non-public proxy classes for those non-public types.
That's no different than the challenge for 
pango_cairo_font_map_set_resolution(), so it's nothing particularly
new ]


(http://mail.gnome.org/archives/language-bindings/2005-May/msg00008.html
has my recommendation for binding gdk_cairo_show_glyph_string())

> How do you handle the Xft ones I listed?

They're not wrapped since there's no way to deal with the things they return or take due to a lack of Perl bindings for the X types.  The same holds for the rest of the backend-specific API, apart from pangocairo.h: cairo has Perl bindings.

I don't know of any other language binding that wraps the Xft stuff.

> (http://mail.gnome.org/archives/language-bindings/2005-May/msg00008.html
> has my recommendation for binding gdk_cairo_show_glyph_string())

(I presume you mean pango_cairo_show_glyph_string here.)

The advice from your mail (wrap gdk_cairo_* as methods on a special context object deriving from cairo_t) hinges on one crucial fact: there's a constructor for this special context object -- gdk_cairo_create.  This enables language bindings to wrap the context somehow so that, from the language's point of view, you have an object which you can call gdk_cairo_* and cairo_* on.

This doesn't work for the various pango_cairo_* functions working on a cairo_t.  There is no special constructor.  Thus I didn't see another way but to wrap those as functions.

Should be fixed.

2007-07-21  Behdad Esfahbod  <behdad@gnome.org>

        Part of Bug 347236 – provide pango_cairo_font_get_scaled_font

        * docs/Makefile.am:
        * docs/pango-sections.txt:
        * docs/tmpl/atsui-fonts.sgml:
        * docs/tmpl/opentype.sgml:
        * docs/tmpl/pango-engine-lang.sgml:
        * docs/tmpl/pango-engine-shape.sgml:
        * docs/tmpl/pangocairo.sgml:
        * pango/pangoatsui.h:
        * pango/pangocairo-atsuifont.h:
        * pango/pangocairo-font.c (pango_cairo_font_get_scaled_font):
        * pango/pangocairo-private.h:
        * pango/pangocairo.h:
        Export PangoCairoFont and cleanup various standard macros.

Yep, this solves the problem nicely.  Thanks.