src/pypdf/generic/_fit.py
1from collections.abc import Sequence
2from typing import Any
3
4from ._base import is_null_or_none
5
6
7class Fit:
8 def __init__(
9 self, fit_type: str, fit_args: Sequence[float | Any | None] = ()
10 ) -> None:
11 from ._base import FloatObject, NameObject, NullObject, NumberObject # noqa: PLC0415
12
13 self.fit_type = NameObject(fit_type)
14 self.fit_args: list[NullObject | FloatObject | NumberObject] = [
15 NullObject() if is_null_or_none(a) else FloatObject(a) for a in fit_args
16 ]
17
18 @classmethod
19 def xyz(
20 cls,
21 left: float | None = None,
22 top: float | None = None,
23 zoom: float | None = None,
24 ) -> "Fit":
25 """
26 Display the page designated by page, with the coordinates (left, top)
27 positioned at the upper-left corner of the window and the contents
28 of the page magnified by the factor zoom.
29
30 A null value for any of the parameters left, top, or zoom specifies
31 that the current value of that parameter is to be retained unchanged.
32
33 A zoom value of 0 has the same meaning as a null value.
34
35 Args:
36 left:
37 top:
38 zoom:
39
40 Returns:
41 The created fit object.
42
43 """
44 return Fit(fit_type="/XYZ", fit_args=(left, top, zoom))
45
46 @classmethod
47 def fit(cls) -> "Fit":
48 """
49 Display the page designated by page, with its contents magnified just
50 enough to fit the entire page within the window both horizontally and
51 vertically.
52
53 If the required horizontal and vertical magnification factors are
54 different, use the smaller of the two, centering the page within the
55 window in the other dimension.
56 """
57 return Fit(fit_type="/Fit")
58
59 @classmethod
60 def fit_horizontally(cls, top: float | None = None) -> "Fit":
61 """
62 Display the page designated by page, with the vertical coordinate top
63 positioned at the top edge of the window and the contents of the page
64 magnified just enough to fit the entire width of the page within the
65 window.
66
67 A null value for ``top`` specifies that the current value of that
68 parameter is to be retained unchanged.
69
70 Args:
71 top:
72
73 Returns:
74 The created fit object.
75
76 """
77 return Fit(fit_type="/FitH", fit_args=(top,))
78
79 @classmethod
80 def fit_vertically(cls, left: float | None = None) -> "Fit":
81 return Fit(fit_type="/FitV", fit_args=(left,))
82
83 @classmethod
84 def fit_rectangle(
85 cls,
86 left: float | None = None,
87 bottom: float | None = None,
88 right: float | None = None,
89 top: float | None = None,
90 ) -> "Fit":
91 """
92 Display the page designated by page, with its contents magnified
93 just enough to fit the rectangle specified by the coordinates
94 left, bottom, right, and top entirely within the window
95 both horizontally and vertically.
96
97 If the required horizontal and vertical magnification factors are
98 different, use the smaller of the two, centering the rectangle within
99 the window in the other dimension.
100
101 A null value for any of the parameters may result in unpredictable
102 behavior.
103
104 Args:
105 left:
106 bottom:
107 right:
108 top:
109
110 Returns:
111 The created fit object.
112
113 """
114 return Fit(fit_type="/FitR", fit_args=(left, bottom, right, top))
115
116 @classmethod
117 def fit_box(cls) -> "Fit":
118 """
119 Display the page designated by page, with its contents magnified just
120 enough to fit its bounding box entirely within the window both
121 horizontally and vertically.
122
123 If the required horizontal and vertical magnification factors are
124 different, use the smaller of the two, centering the bounding box
125 within the window in the other dimension.
126 """
127 return Fit(fit_type="/FitB")
128
129 @classmethod
130 def fit_box_horizontally(cls, top: float | None = None) -> "Fit":
131 """
132 Display the page designated by page, with the vertical coordinate top
133 positioned at the top edge of the window and the contents of the page
134 magnified just enough to fit the entire width of its bounding box
135 within the window.
136
137 A null value for top specifies that the current value of that parameter
138 is to be retained unchanged.
139
140 Args:
141 top:
142
143 Returns:
144 The created fit object.
145
146 """
147 return Fit(fit_type="/FitBH", fit_args=(top,))
148
149 @classmethod
150 def fit_box_vertically(cls, left: float | None = None) -> "Fit":
151 """
152 Display the page designated by page, with the horizontal coordinate
153 left positioned at the left edge of the window and the contents of the
154 page magnified just enough to fit the entire height of its bounding box
155 within the window.
156
157 A null value for left specifies that the current value of that
158 parameter is to be retained unchanged.
159
160 Args:
161 left:
162
163 Returns:
164 The created fit object.
165
166 """
167 return Fit(fit_type="/FitBV", fit_args=(left,))
168
169 def __str__(self) -> str:
170 if not self.fit_args:
171 return f"Fit({self.fit_type})"
172 return f"Fit({self.fit_type}, {self.fit_args})"
173
174
175DEFAULT_FIT = Fit.fit()