After an evaluation, GNOME has moved from Bugzilla to GitLab. Learn more about GitLab.
No new issues can be reported in GNOME Bugzilla anymore.
To report an issue in a GNOME project, go to GNOME GitLab.
Do not go to GNOME Gitlab for: Bluefish, Doxygen, GnuCash, GStreamer, java-gnome, LDTP, NetworkManager, Tomboy.
Bug 92514 - pangomm has some bugs and incomplete documentation
pangomm has some bugs and incomplete documentation
Status: RESOLVED FIXED
Product: gtkmm
Classification: Bindings
Component: general
2.0
Other other
: Normal normal
: ---
Assigned To: gtkmm-forge
gtkmm-forge
Depends on:
Blocks:
 
 
Reported: 2002-09-04 20:23 UTC by Martin Schulze
Modified: 2004-12-22 21:47 UTC
See Also:
GNOME target: ---
GNOME version: ---


Attachments
pangomm-refdoc.diff.gz: (Almost) complete documentation for pangomm and bug and API fixes. (15.26 KB, application/octet-stream)
2002-09-04 20:25 UTC, Martin Schulze
Details
pango_docs_override.xml.gz: Some overrides for inappropriate pango docs. No diff because there is nothing to diff against :( (2.33 KB, application/octet-stream)
2002-09-04 20:28 UTC, Martin Schulze
Details
pangomm-api-review-complete.tar.gz: Finally! See ChangeLog entry in the diff file for a complete list of changes. (22.28 KB, application/octet-stream)
2002-09-09 16:03 UTC, Martin Schulze
Details

Description Martin Schulze 2002-09-04 20:23:40 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.
Comment 1 Martin Schulze 2002-09-04 20:25:31 UTC
Created attachment 10903 [details]
pangomm-refdoc.diff.gz: (Almost) complete documentation for pangomm and bug and API fixes.
Comment 2 Martin Schulze 2002-09-04 20:28:09 UTC
Created attachment 10904 [details]
pango_docs_override.xml.gz: Some overrides for inappropriate pango docs. No diff because there is nothing to diff against :(
Comment 3 Murray Cumming 2002-09-06 16:13:10 UTC
Why bother to implement the =Language() thing if you know that it 
needs to be replaced?
Comment 4 Martin Schulze 2002-09-06 18:23:13 UTC
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.
Comment 5 Martin Schulze 2002-09-06 20:49:32 UTC
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.
Comment 6 Martin Schulze 2002-09-09 16:03:00 UTC
Created attachment 10980 [details]
pangomm-api-review-complete.tar.gz: Finally! See ChangeLog entry in the diff file for a complete list of changes.
Comment 7 Martin Schulze 2002-09-09 16:11:04 UTC
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 :)
Comment 8 Murray Cumming 2002-09-10 10:41:49 UTC
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?
Comment 9 Martin Schulze 2002-09-10 15:40:15 UTC
- 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.
Comment 10 Murray Cumming 2002-09-10 19:39:57 UTC
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.
Comment 11 Martin Schulze 2002-09-10 21:24:50 UTC
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...).
Comment 12 Murray Cumming 2002-09-11 07:02:34 UTC
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.
Comment 13 Martin Schulze 2002-09-11 18:58:51 UTC
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 :)
Comment 14 Murray Cumming 2002-09-12 21:51:26 UTC
I have done this now.