GNOME Bugzilla – Bug 98013
Use typedef for Pango units?
Last modified: 2018-05-22 12:01:52 UTC
Pango uses 'int' to represent both device units and Pango units (1/PANGO_SCALE device units). Working out whether an 'int' represents device units or Pango units comes down to reading the documentation, but sometimes that doesn't tell you. For example, the x_pos argument to pango_glyph_string_x_to_index() is documented as "the x offset (in thousands of a device unit)", but the x_pos argument to pango_glyph_string_index_to_x() is documented as "location to store result" Making a typedef for Pango units, e.g.: typedef int PangoUnit; in pango-types.h and using the typedef for all parameters and return values that are in Pango units will make the uses of Pango units obvious even if someone reads just the header files instead of the documentation.
Note that the typedef is already there (PangoGlyphUnit), though with an outdated comment. I'm not sure if I really think that using it everywhere would be a good idea... it would make everything look a bit clumsier. The rule is really simple ... everything is PangoUnits except for: - Functions with _pixels() in their name - Coordinates in backend-specific rendering functions
*** Bug 101691 has been marked as a duplicate of this bug. ***
If we WONTFIX this, we should remove all the usages of PangoGlyphUnit.
So, Owen, which side is preferred? WONTFIX or FIXED?
I tend to prefer fixing this. I prefer typdef int PangoUnit and make PangoGlyphUnit an alias for it. Any objections?
I really have no strong feeling about this at all. Using PangoUnit is just a little strange on theoretical grounds ... every time you provide an integer to a function, it has some set of dimensions ... why is this one special? (And C typedefs don't really work for dimensioned quantities ... since there are free conversions between them.) But if it improves the self-documentation of the user interface, then it may be a good change. I don't see any inherent problems. (if you are paranoid, you might want to check with Murray Cumming to see if might cause problems for gtkmm, but I *think* all integer typedefs are mangled the same way in C++) So, go with your preference, flip a coin, or whatever. :-) I assume by "make PangoGlyphUnit an alias for it" - you mean leave it as a typedef but remove all other uses?
Yes, it will remind you about the scale every time you see the API. It's not about the range, it's the scale that is a problem... Of course, as you said, we cannot enforce anything at this stage without breaking source compatibility... I plan to typedef PangoUnit PangoGlyphUnit to make it explicit that they are the same thing, and yes, remove all other uses. Cheers.
-- GitLab Migration Automatic Message -- This bug has been migrated to GNOME's GitLab instance and has been closed from further activity. You can subscribe and participate further through the new bug through this link to our GitLab instance: https://gitlab.gnome.org/GNOME/pango/issues/5.