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/// When arranging content across multiple columns, use @colbreak to explicitly
15/// continue in the next column.
16///
17/// = Example <example>
18/// ```example
19/// #columns(2, gutter: 8pt)[
20///   This text is in the
21///   first column.
22///
23///   #colbreak()
24///
25///   This text is in the
26///   second column.
27/// ]
28/// ```
29///
30/// = #short-or-long[Page Level][Page-level columns] <page-level>
31/// If you need to insert columns across your whole document, use the `{page}`
32/// function's @page.columns[`columns` parameter] instead. This will create the
33/// columns directly at the page-level rather than wrapping all of your content
34/// in a layout container. As a result, things like @pagebreak[pagebreaks],
35/// @footnote[footnotes], and @par.line[line numbers] will continue to work as
36/// expected. For more information, also read the
37/// @guides:page-setup:columns[relevant part of the page setup guide].
38///
39/// = #short-or-long[Breaking Out][Breaking out of columns] <breaking-out>
40/// To temporarily break out of columns (e.g. for a paper's title), use
41/// parent-scoped floating placement:
42///
43/// #example(
44///   single: true,
45///   ```
46///   #set page(columns: 2, height: 150pt)
47///
48///   #place(
49///     top + center,
50///     scope: "parent",
51///     float: true,
52///     text(1.4em, weight: "bold")[
53///       My document
54///     ],
55///   )
56///
57///   #lorem(40)
58///   ```
59/// )
60#[elem]
61pub struct ColumnsElem {
62    /// The number of columns.
63    #[positional]
64    #[default(NonZeroUsize::new(2).unwrap())]
65    pub count: NonZeroUsize,
66
67    /// The size of the gutter space between each column.
68    #[default(Ratio::new(0.04).into())]
69    pub gutter: Rel<Length>,
70
71    /// The content that should be layouted into the columns.
72    #[required]
73    pub body: Content,
74}
75
76/// Forces a column break.
77///
78/// The function will behave like a @pagebreak[page break] when used in a single
79/// column layout or the last column on a page. Otherwise, content after the
80/// column break will be placed in the next column.
81///
82/// = Example <example>
83/// ```example
84/// #set page(columns: 2)
85/// Preliminary findings from our
86/// ongoing research project have
87/// revealed a hitherto unknown
88/// phenomenon of extraordinary
89/// significance.
90///
91/// #colbreak()
92/// Through rigorous experimentation
93/// and analysis, we have discovered
94/// a hitherto uncharacterized process
95/// that defies our current
96/// understanding of the fundamental
97/// laws of nature.
98/// ```
99#[elem(title = "Column Break")]
100pub struct ColbreakElem {
101    /// If `{true}`, the column break is skipped if the current column is
102    /// already empty.
103    #[default(false)]
104    pub weak: bool,
105}
typst_library/layout/columns.rs

typst_library/layout/
columns.rs
