Quo vadis, .write()?

[gmischler]

Now that the .multicell() refactoring #308 by @oleksii-shymann has landed (congrats, and thanks for implementing my feature request!), it opens the path to several other possible changes.

Here's what I imagine could be done, in relatively small steps to keep it manageable. I'm presenting this for discussion, to discuss feasability and maybe others will come up with possibilities that I've missed. It's probably best to take this as a proposal for a road map, which may eventually result in a series of feature request issues.

1. Refactor .write() to use the new line wrapping code

This will eliminate redundant code and enable .write() to use soft-hyphens.

2. Enable text alignment for .write()

.write() currently only supports left alignment, but we also want right, center, and justify. This will require to keep a cache of the text already added, at least until the current line is full. The challenge is what to do with the last line. The simplest solution might be to trigger it's addition through a manual newline (eg. .nl()). But that would be a confusing change of semantics, and also a dead end in terms of functionality.
The more elegant and pythonic way is to create a class TextArea , which acts as a context manager, and handles the alignment of the text added within its scope, using the page margins as .write() already does on its own.

	with TextArea(pdf, align="justify"):
		pdf.write(txt="lorem ipsum...")
		pdf.set_font(x, y, z)
		pdf.write(txt="lorem ipsum...")

Of course, only one such context can be active at any time.

For backwards compatibility, any .write() call outside of such a context should keep working as it does now.

3. Flexible text column width

Having to manipulate the page margins in order to create multiple columns of text is somewhat annoying. A simple solution is a subclass TextColumn, which accepts its own left and right boundaries.
In fact, it should probably accept arguments to specify the boundaries for several columns, in order to fully automate multi-column layouts.

4. Other text outline shapes

But why limit ourselfes to just straight columns? All we need to extend on that are a few more subclasses:

class TextPolygon(TextArea): ...
class TextEllipse(TextArea): ...
class TextRectangle(TextArea): ...
class TextRegularPolgyon(TextArea): ...

This will require a slight modification to the line wrapping code, so that in the presence of a text area context, it won't just use a fixed width, but asks the context for each line where it should start and end.
The idea is that for any line of text (a vertical space between pdf.y and pdf.y + lineheight), the context manager instance will determine the maximum horizontal space for text it could hold within.

Using an outline that is defined in all directions (not just on the sides as with a column), these are likely to be restricted to a single page. Consequently we need to think about what happens when the user supplies more text than fits in the given area. Most likely the surplus text will simply be dropped with a warning. But we could also give it a callback, in order for the client code to create a new shape, possibly on another page.

Any new call to .write() simply continues on the same line as the previous one has ended, but possibly with a radically different font size. This raises the issue of vertical alignment, which can probably be solved with a vertical_align="top|bottom|middle" argument.

Given that our lateral boundaries are not always vertical anymore, it may also be tricky to figure out which line height actually applies to a given line, which then in turn could make the horizontal extent ambiguous (and vice versa, in the worst case).

5. Combine shapes

This one is a possible solution to issue #245.

While using one shape at a time is straightforward enough, there's also the possibility to combine several of them by means of modification. You start with one of the shapes serving as context, and then extend or reduce its area by adding and/or subtracting other shapes from it:

	pdf.set_y(20)
	with TextColumn(pdf, left=20, right=150, align="justify") as col:
		# cut a quarter circle off the top left
		col.remove(TextEllipse(pdf, x=20, y=29, radius_x=30, radius_y=30)
		# extend a stretch on the right edge
		col.add(TextRectancle(pdf, x=150, y=150, w=20, h=30)
		# a diamond shaped hole in the middle
		col.remove(TextRegularPolygon(pdf, n=4, x=70, y=200, size=40, rotate=45)
		pdf.write(txt="lorem ipsum ...")

After the context has determined its own width for a line of text, it will ask each removed shape which range it will exclude (by its outer bounds), and each added shape which range it will enable (by its inner bounds). It will do so in the sequence in which they have been applied, and change its writeable width accordingly.

I don't know what the best algorithm is to do that, but the result should be one or several stretches to place text on that line (several if we created a gap in the middle).

6. Use image data to shape text

TextImageMap is probably the most ambitious one, so it might be regarded as a bonus round. It will need a PIL.Image.Image instance (maybe .image() should be made to return one?).
Then it can be configured with one or several methods like:

	with TextColumn(pdf, left=20, right=150, align="justify") as col:
		imap = col.remove(TextImageMap(pdf, x=x, y=y, w=w, h=h, image=image, combine="any")
		# assuming 8-bit transparency, less than half transparent
		imap.transparency(mode="lower_than", value=128)
		# LUV color space less than 3/4 brightness
		imap.luv_lightness(mode="lower_than", value=192)

The combine="any" (out of "any"|"all") means that either condition will block the text (too dark or not transparent enough), with "all" requiring them all to be true for the same pixel. Many other criteria could be implemented. Most likely it will be helpful to scale the image down first, to make it more efficient and to blur any extreme single pixels away.

Questions to consider

A few of the issues that need to be considered before implementation may be:

• In addition to .write(), is there any useful purpose for .cell(), .multicell(), and/or .text() within a text area? I don't currently see one, but you never know...
• Should the normal .write() method of FPDF() be adapted for use within those context managers, or is it more practical for them to have a .write() method (wrapping the former with the necessary modifications)?
• Is there a way to adapt .write_html() as well?
• Any better ways to structure the whole architecture or to more adequately name its components?

Any thoughts on how to further improve those concepts?

Anyone wants to have fun with this?

[Lucas-C]

Hi @gmischler. Thanks for opening this discussion!

1. Refactor .write() to use the new line wrapping code

Agreed, seems like the way to go forward. I opened #340 in order to track this.

2. Enable text alignment for .write()

What is the need here exactly?
Maybe text alignment could only be supported by cell & multi_cell?

3. Flexible text column width

FYI there is currently a tutorial covering this:
https://pyfpdf.github.io/fpdf2/Tutorial.html#tuto-4-multi-columns

I'm not against making this an internal feature, but could you please give details on that TextColumn class you have in mind?
What would be its methods?

4. Other text outline shapes

[...] The idea is that for any line of text, the context manager instance will determine the maximum horizontal space for text it could hold within.

Sounds great!
Do you aim to implement this in FPDF.write? Why in this method?

Most likely the surplus text will simply be dropped with a warning.

I disagree here. In order to follow the principle of least astonishment, I think the text rendering should continue onto the next page, or an exception should be raised to inform the user of the issue.

This raises the issue of vertical alignment, which can probably be solved with a vertical_align="top|bottom|middle" argument.

FYI, issue #210 is already open about this.

You ask very interesting open questions at the end 😄
I do not have definitive answers for them, but I tend to believe in some form of do-ocracy regarding such features:
the contributor who produces the code and submits the PR gets to come up with the solution that best fits their vision!

[gmischler]

1. Refactor .write() to use the new line wrapping code

Agreed, seems like the way to go forward. I opened #340 in order to track this.

And someone already adopted it! We'll see how it goes.

2. Enable text alignment for .write()

What is the need here exactly?

Because we can! 😁
It is also a good basis for the items below, which wouldn't make much sense without it.

3. Flexible text column width

FYI there is currently a tutorial covering this: https://pyfpdf.github.io/fpdf2/Tutorial.html#tuto-4-multi-columns
I'm not against making this an internal feature, but could you please give details on that TextColumn class you have in mind? What would be its methods?

These are mostly general ideas for now, not fleshed out plans.
I'm actually not sure if such a class even needs extra methods. The most basic implementation would just take a series of left-right position pairs, and maybe a few configuration options. It will obviously have to interact with .accept_page_break() somehow, maybe temporarily replacing it by an injected version.
There are several variations possible (single vs. multicolumn, equal vs. varying width, etc.), which may get solved either by configuration options or by seperate subclasses.
It gets a little more involved if we want to eg. balance the length of columns...

[...] The idea is that for any line of text, the context manager instance will determine the maximum horizontal space for text it could hold within.

Sounds great! Do you aim to implement this in FPDF.write? Why in this method?

It makes the most sense for .write(), which was designed to flow text within external boundaries. In contrast, .multicell() is by definition a rectangular box with its own dimensions/background/borders. It may be possible to adapt it as well, but I wouldn't give that a high priority.

Most likely the surplus text will simply be dropped with a warning.

I disagree here. In order to follow the principle of least astonishment, I think the text rendering should continue onto the next page, or an exception should be raised to inform the user of the issue.

There are a lot of possible overflow strategies, ideally applied at the users choice. If someone places a TextCircle() on a page, and fills it with text, would you expect an identical circle to appear on the next page? I don't think I would, but that may be just me...
My idea was to differentiate between column based layouts that wrap to the next page, and outline based layouts that don't (at least not by default). The former are better suited for automated document generation, the latter more for individually crafted layouts.
Whether overflowing causes a warning, an exception, or some other kind of feedback (eg. a return value), is open to debate, and ultimately at the discretion of the implementer.

This raises the issue of vertical alignment, which can probably be solved with a vertical_align="top|bottom|middle" argument.

FYI, issue #210 is already open about this.

A very similar topic, but I don't think it's the same.
There are several different types of vertical alignment.
In our case here, it's about the alignment of differently sized chunks of text within the same line. Here the text with the smaller font needs to know how it relates to the larger one.
#210 talks about the vertical alignment of one or several lines of text within a (multi)cell, in the context of formatting a table.

I tend to believe in some form of do-ocracy regarding such features: the contributor who produces the code and submits the PR gets to come up with the solution that best fits their vision!

There are many bridges here that will be crossed by means of implementation! 😉

But sometimes it is useful to look at the big picture first, and think about how various different parts of a system might best play together. At the very least, it helps in creating a more consistent API.

[gmischler]

Current status:

Phase 1 has been implemented in PRs #308 and #346.

Phase 2a is also done. PRs #511 and #519 provide the foundation, making it technically possible to horizontally align text that varies in almost any properties (font, size, style, stretching, spacing, etc.).
Phase 2b will build on top of that, and provide an end-user API with a hierarchy of TextRegion() classes defining the areas to fill with text.

More to follow...

[gmischler]

Nearly a year later, we have some more progress:

The PR #897 (still a work in progress) implements the following:

• Phase 2b with the basic infrastructure to manage TextRegions.
• Phase 3 with columns of settable width.

[gmischler]

With release 2.7.6, #897 has been merged (still declared "experimental").

It implements the basic mechanisms and a new method FPDF.text_columns(). Columns can contain paragraphs with their own horizontal alignment and top and bottom margins. Multiple columns on a page can have their height balanced if desired.
Also, FPDF.write_html() has been modified to use text_columns(ncols=1) for its text output (except within table cells). This makes it possible to have inline formatting changes and links within paragraphs without starting a new line on every tag as was the case before.

The next step will be to add a special type of "paragraph" for images to be rendered within columns.
This is a requirement for converting table cells to text regions, which will happen right after.