typst_library/layout/
columns.rs

1use std::num::NonZeroUsize;
2
3use crate::foundations::{Content, elem};
4use crate::layout::{Length, Ratio, Rel};
5
6/// Separates a region into multiple equally sized columns.
7///
8/// The `column` function lets you separate the interior of any container into
9/// multiple columns. It will currently not balance the height of the columns.
10/// Instead, the columns will take up the height of their container or the
11/// remaining height on the page. Support for balanced columns is planned for
12/// the future.
13///
14/// # Page-level columns { #page-level }
15/// If you need to insert columns across your whole document, use the `{page}`
16/// function's [`columns` parameter]($page.columns) instead. This will create
17/// the columns directly at the page-level rather than wrapping all of your
18/// content in a layout container. As a result, things like
19/// [pagebreaks]($pagebreak), [footnotes]($footnote), and [line
20/// numbers]($par.line) will continue to work as expected. For more information,
21/// also read the [relevant part of the page setup
22/// guide]($guides/page-setup/#columns).
23///
24/// # Breaking out of columns { #breaking-out }
25/// To temporarily break out of columns (e.g. for a paper's title), use
26/// parent-scoped floating placement:
27///
28/// ```example:single
29/// #set page(columns: 2, height: 150pt)
30///
31/// #place(
32///   top + center,
33///   scope: "parent",
34///   float: true,
35///   text(1.4em, weight: "bold")[
36///     My document
37///   ],
38/// )
39///
40/// #lorem(40)
41/// ```
42#[elem]
43pub struct ColumnsElem {
44    /// The number of columns.
45    #[positional]
46    #[default(NonZeroUsize::new(2).unwrap())]
47    pub count: NonZeroUsize,
48
49    /// The size of the gutter space between each column.
50    #[default(Ratio::new(0.04).into())]
51    pub gutter: Rel<Length>,
52
53    /// The content that should be layouted into the columns.
54    #[required]
55    pub body: Content,
56}
57
58/// Forces a column break.
59///
60/// The function will behave like a [page break]($pagebreak) when used in a
61/// single column layout or the last column on a page. Otherwise, content after
62/// the column break will be placed in the next column.
63///
64/// # Example
65/// ```example
66/// #set page(columns: 2)
67/// Preliminary findings from our
68/// ongoing research project have
69/// revealed a hitherto unknown
70/// phenomenon of extraordinary
71/// significance.
72///
73/// #colbreak()
74/// Through rigorous experimentation
75/// and analysis, we have discovered
76/// a hitherto uncharacterized process
77/// that defies our current
78/// understanding of the fundamental
79/// laws of nature.
80/// ```
81#[elem(title = "Column Break")]
82pub struct ColbreakElem {
83    /// If `{true}`, the column break is skipped if the current column is
84    /// already empty.
85    #[default(false)]
86    pub weak: bool,
87}
typst_library/layout/columns.rs

typst_library/layout/
columns.rs
