pango_layout_set_height()

[Behdad Esfahbod <behdad behdad org>]

Hi,

In pango-1.19.3 that just hit the door is the new API:

void pango_layout_set_height (PangoLayout *layout,
                              int          height);

Copying from release notes:

========================================================================
This sets the height to which the #PangoLayout should be ellipsized at.
There are two different behaviors, based on whether @height is positive
or negative.

If @height is positive, it will be the maximum height of the layout.
Only lines would be shown that would fit, and if there is any text
omitted, an ellipsis added.  At least one line is included in each
paragraph regardless of how small the height value is.  A value of zero
will render exactly one line for the entire layout.

If @height is negative, it will be the (negative of) maximum number of
lines per paragraph.  That is, the total number of lines shown may well
be more than this value if the layout contains multiple paragraphs of
text.  The default value of -1 means that first line of each paragraph
is ellipsized.

Height setting only has effect if a positive width is set on @layout and
ellipsization mode of @layout is not %PANGO_ELLIPSIZE_NONE.  The
behavior is undefined if a height other than -1 is set and ellipsization
mode is set to %PANGO_ELLIPSIZE_NONE, and may change in the future.

There are still bugs remaining to be fixed, notably bug 511172 (which
will be fixed before 1.20), and bug 511171 (which will be fixed in a
future version).
========================================================================

The implementation is not perfect yet, but I wanted to get this one in
Pango 1.20.  I hear that this is a quite welcome API for small devices.
Think being able to render two lines of Subject line with ellipsization
enabled on a small screen.  Another use of this is in labels.  You set
width and height to the size allocation and voila.

Anyway, issues with it:

  - I don't like the fact that negative numbers are per-paragraph
limits.  But this was needed to keep compatibility with previous
releases.  Otherwise a third mode needed to be introduced as default to
behave as previous releases.  I don't have any concrete uses for the
negative cases other than -1 at this time, so it's not a huge issue to
me.  But read below.

  - Currently, for positive heights, at least two lines are rendered.
That's straight a bug, that I plan to fix for 1.20 release, but the
ideal fix needs quite some code restructuring.  The reason for this
being that currently pango uses the height of the previous line as the
estimate for the height of next lines, and if two such lines wouldn't
fit, it will ellipsize the next line.  Other than obvious problems with
that approach, it doesn't work for the first line.  To be able to fix it
properly we need to be able to back up in the middle of laying out a
line and decide that the line should be ellipsized, or worse, that
previous line should be ellipsized.  This is bug 511172.

  - Currently, even for ellipsize modes START and MIDDLE, the last line
is ellipsized (start or middle of last line...).  That's not good
either, at least not for START.  This is bug 511171.  Fixing it requires
being able to break layout lines end to start (which is a useful feature
in itself).  That one is bug 460828.

  - Currently if ellipsize is set to NONE, height setting is ignored and
all paragraphs are rendered with one line.  That's compatible with
previous versions.  I have marked in the docs undefined to set height to
anything other than -1 when ellipsize is NONE.  The idea is change the
behavior in the future such that if not ellipsizing and no width set
(width=-1), then height setting respected.  For example, if you set
height to -2, a width will be chosen such that at least one paragraph
has two lines, and none more than two...  That may be useful in
rendering text in dialogs for example where currently GTK+ has a dirty
hack to limit width of a dialog to half of the screen width to avoid
wide single-line dialogs.


That's it for now.  I would like to get comments about to these, to see
if the API should remain in 1.20 with these semantics, or semantics
changed, or the API should be retracted for 1.20.


Thanks,
-- 
behdad
http://behdad.org/

"Those who would give up Essential Liberty to purchase a little
 Temporary Safety, deserve neither Liberty nor Safety."
        -- Benjamin Franklin, 1759