GNOME Bugzilla – Bug 92514
pangomm has some bugs and incomplete documentation
Last modified: 2004-12-22 21:47:04 UTC
Sorry, for the general summary. Straight forwardness from now on: here comes the ChangeLog :-) * api_status.txt: Reflect recent API additions to pangomm. * TODO: copy the TODO's from this ChangeLog. * tools/pm/DocParser.pm: Comment out conditional if-clause around conversion from C documentation to C++. It prevented conversion of the documentation in *_docs_override.xml which currently is in the same style as *_docs.xml and lead to mistakes in our overridden gtk documentation. * pangomm/src/attributes.hg: Make Attr* default constructors protected. They don't produce legal attribute objects. Attribute::Attribute() produces an object with gobject_==0. This is handled as if it were an attribute of type ATTR_INVALID and allows wrapping of NULL return values from pango c functions. * pangomm/src/attriter.ccg: Correct possible bug in AttrIter::get_font(). (Taken a hint in pagno c ref doc serious :) * pangomm/src/attrlist.hg: Add default argument for: explicit AttrList::AttrList(const Glib::ustring&, gunichar accel_marker=0). * pangomm/src/context.hg: - Remove _WRAP_CREATE(). It can't possibly initialize the Pango::Context object correctly because some PangoFontMap is needed from a pango backend. - Add default argument Language() for the language parameter of Context::get_metrics. TODO: Use a function overload instead. * pangomm/src/coverage.{hg,ccg}: - Change Coverage::to_bytes() to return a Glib::ArrayHandle<unsigned char> instead of an guchar* array that needs to be freed with g_free() by hand. - Remove Coverage::copy(). The pango docs state that is is superfluous. * pangomm/src/font.hg: - Add default argument Language() for the language parameter of Font::get_metrics(). TODO: Use a function overload instead. - TODO: Ask list whether we really need Font::get_glyph_extents_{ink,logical}_rect_only(). * pangomm/src/fontdescription.hg: TODO: Investigate the following: FontDescription::{set_family_static,merge_static} look as if they could lead to undefined results and corrupted data. * pangomm/src/glyph.{hg,ccg}: - Add Glib::wrap(PangoGlyphInfo*). I forget it last time. - Comment out set_* in GlyphInfo and GlyphGeometry. They don't make sense as GlyphInfo and GlyphGeometry are merely output classes to the user. * pangomm/src/glyphstring.{hg,ccg}: - Add GlyphString::GlyphString(const Glib::ustring&, const Analysis&). This wraps pango_shape which didn't do up to now. - Make GlyphString::get_logical_widths, GlyphString::index_to_x and GlyphString::x_to_index calculate take the size of the passed text parameter from the Glib::ustring itself rather than demanding an extra argument. GlyphString::get_logical_width now allocaltes an array to store the results rather than expecting the user to do this. * pangomm/src/item.{hg,ccg}: Add Item::get_segment() and Item::shape(). The former computes the text segment that is covered by the item (convenience one-line-function not available in pango), the latter wraps the new GlyphString constructor and thus pango_shape(). * pangomm/src/language.{hg,ccg}: - Add Language::Language() that constructs an object with gobject_==0. - Adapt Language::get_string to allow for objects with gobjct_==0. - TODO: Change const char* into std::string. * pangomm/src/layout.ccg: Bug fix: use text.bytes() instead of ext.size(). * pangomm/src/layout.hg: Bug fix: use refreturn parameter of _WRAP_METHOD for Layout::get_context() and Layout::get_line(). * pangomm/src/layoutiter.hg: Bug fix: use refreturn parameter of _WRAP_METHOD for LayoutIter::get_line(). * pangomm/src/{*.hg,*.ccg}: Add lots of documentation. I hope that some things I had to learn the hard way become clear in the class description of Pango::Context.
Created attachment 10903 [details] pangomm-refdoc.diff.gz: (Almost) complete documentation for pangomm and bug and API fixes.
Created attachment 10904 [details] pango_docs_override.xml.gz: Some overrides for inappropriate pango docs. No diff because there is nothing to diff against :(
Why bother to implement the =Language() thing if you know that it needs to be replaced?
I did it before I knew and wanted to get this patch ready. Is this so important? I will work on the TODO items now - if you insist I can recreate the whole patch afterwards.
I made up my mind and decieded that I will indeed recreate the patch. I solved all TODO items (apart from the examples that need to be added) but made more changes that affect a lot of file: A lot of get_* and other functions are now "const" and a wrapper class for PangoLayoutRun has been added. Now I have a good feeling that the pango API review is complete. I will attach the new patch as soon as there is some feedback to the thread "Two optional return values in pango functions: what to do?" on the ml.
Created attachment 10980 [details] pangomm-api-review-complete.tar.gz: Finally! See ChangeLog entry in the diff file for a complete list of changes.
The latest attachment "pangomm-api-review-complete.tar.gz" is what I have come up with now. It replaces the former "pangomm-refdoc.diff.gz" attachment. I do hope it solves all outstanding pangomm API issues. Since the only response to the mentioned ml thread has been Naofumi's who wants a clear, convenient API, I've spent another two hours adding a number of functions for similar cases like Font::get_glyph_extents() that return a single Pango::Rectangle. Murray, could you please check whether the patch builds with gcc 3.x? I still haven't reached a cvsmaster so I'd also ask you to apply the patch afterwards. (It does not depend on the patch that adds auto-doc-generation from pango/atk/gdk doc :)
Applied. Thanks a lot for all this work. Where you have used std::string, have you checked that you really should not be using Glib::ustring? Are you sure that the string would _never_ be UTF8?
- Hm, for Attribute::register_type() the std::string parameter is "currently unused" according to Pango docs. There is no hint what use it might get in the future. Would you prefer this to be Glib::ustring? - Color::parse() takes a std::string: the color names are the ones used by X11 and I don't expect those to be UTF-8 in the future. - The internal string representation of a Language has RFC-3066 format. I haven't read http://www.faqs.org/rfcs/rfc3066.html in detail but a quick look didn't give any hints about the usage of UTF strings for language tags which wouldn't make much sense to me anyway.
If you aren't _certain_ that something will never be UTF8, then it must use Glib::ustring. Don't impose constraints if you are not sure. It's easy to give a std::string to a Glib::ustring, but it's a theoreticaL loss of data to give a Glib::ustring to a std::string.
Okay, then Attribute::register_type() will get a Glib::ustring argument. The other two certainly won't ever be UTF-8. I will make the patch tomorrow (if anoncvs is in sync by then...).
Are you 100% certain that things such as the X11 colour can not be UTF8? If you have not looked at the specification recently then I don't think that you can be 100% certain.
The "specification" in the form of the man-page of the program "rgb" that I found doesn't mention anything about the string format of the color names. Currently, all names are english even in my german distribution. Obviously we cannot be 100% sure that this is the case for future releases and I don't see how a Glib::ustring could hurt here. So I'll change the parameter of Color::parse() to Glib::ustring, too. (This seems to be along your line of argumentation :)
I have done this now.