Skip to content

Commit

Permalink
Minor doc update
Browse files Browse the repository at this point in the history
  • Loading branch information
Lucas-C committed Jan 21, 2025
1 parent bb3aaa1 commit ba55184
Show file tree
Hide file tree
Showing 2 changed files with 8 additions and 17 deletions.
21 changes: 5 additions & 16 deletions docs/TextColumns.md
Original file line number Diff line number Diff line change
@@ -1,24 +1,18 @@
_New in [:octicons-tag-24: 2.7.6](https://github.com/py-pdf/fpdf2/blob/master/CHANGELOG.md)_

**Notice:** As of fpdf2 release 2.7.6, this is an experimental feature. Both the API and the functionality may change before it is finalized, without prior notice.


## Text Columns ##

The `FPDF.text_columns()` method allows to create columnar layouts, with one or several columns. Columns will always be of equal width.

### Parameters ###

Beyond the parameters common to all text regions, the following are available for text columns:

* l_margin (float, optional) - override the current left page margin.
* r_margin (float, optional) - override the current right page margin.
* ncols (float, optional) - the number of columns to generate (Default: 2).
* gutter (float, optional) - the horizontal space required between each two columns (Default 10).
* balance (bool, optional) - Create height balanced columns, starting at the current height and ending at approximately the same level.
* `l_margin` (float, optional) - override the current left page margin.
* `r_margin` (float, optional) - override the current right page margin.
* `ncols` (float, optional) - the number of columns to generate (Default: 2).
* `gutter` (float, optional) - the horizontal space required between each two columns (Default 10).
* `balance` (bool, optional) - Create height balanced columns, starting at the current height and ending at approximately the same level.

### Methods ###

Text columns support all the standard text region methods like `.paragraph()`, `.write()`, `.ln()`, and `.render()`. In addition to that:

* `.new_column()` - End the current column and continue at the top of the next one.
Expand All @@ -27,9 +21,7 @@ A FORM_FEED character (`\u000c`) in the text will have the same effect as an exp

Note that when used within balanced columns, switching to a new column manually will result in incorrect balancing.


#### Single-Column Example ####

In this example an inserted paragraph is used in order to format its content with justified alignment, while the rest of the text uses the default left alignment.

```python
Expand All @@ -53,7 +45,6 @@ with cols:
![Single Text Column](tcols-single.png)

#### Multi-Column Example

Here we have a layout with three columns. Note that font type and text size can be varied within a text region, while still maintaining the justified (in this case) horizontal alignment.

```python
Expand All @@ -73,7 +64,6 @@ with pdf.text_columns(text_align="J", ncols=3, gutter=5) as cols:
![Three Text Columns](tcols-three.png)

#### Balanced Columns

Normally the columns will be filled left to right, and if the text ends before the page is full, the rightmost column will be shorter than the others.
If you prefer that all columns on a page end on the same height, you can use the `balance=True` argument. In that case a simple algorithm will be applied that attempts to approximately balance their bottoms.

Expand Down Expand Up @@ -102,7 +92,6 @@ Note that column balancing only works reliably when the font size (specifically


### Possible future extensions

Those features are currently not supported, but Pull Requests are welcome to implement them:

* Columns with differing widths (no balancing possible in this case).
Expand Down
4 changes: 3 additions & 1 deletion docs/TextRegion.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@ Text regions are a hierarchy of classes that enable to flow text within a given
There are two general categories of regions. One defines boundaries for running text that will just continue in the same manner one the next page. Those include columns and tables. The second category are distinct shapes. Examples would be a circle, a rectangle, a polygon of individual shape or even an image. They may be used individually, in combination, or to modify the outline of a multipage column. Shape regions will typically not cause a page break when they are full. In the future, a possibility to chain them may be implemented, so that a new shape will continue with the text that didn't fit into the previous one.

The currently implemented text regions are:

* [Text Columns](TextColumns.html)

Other types like Table cells, shaped regions and combinations are still in the design phase, see [Quo vadis, .write()?](https://github.com/py-pdf/fpdf2/discussions/339).
Expand All @@ -19,7 +20,7 @@ Using the different region types and combination always follows the same pattern
* future: (_If desired, add or subtract other shapes from it (with geometric regions)_).
-->
* Use the `.write()` method of this text region in order to feed text into its buffer.
* Best practise is to use the region instance as a context manager for filling.
* Best practice is to use the region instance as a context manager for filling.
* Text will be rendered automatically after closing the context.
* When used as a context manager, you can change all text styling parameters within that context, and they will be used by the added text, but won't leak to the surroundings
* Alternatively, eg. for filling a single column of text with the already existing settings, just use the region instance as is. In that case, you'll have to explicitly use the `render()` method after adding the text.
Expand All @@ -32,6 +33,7 @@ The graphic shows the relationship of page, text areas and paragraphs (with vary

### Text Start Position ###
When rendering, the vertical start position of the text will be at the lowest one out of:

* the current y position
* the top of the region (if it has a defined top)
* the top margin of the page.
Expand Down

0 comments on commit ba55184

Please sign in to comment.