Mercurial > hgrepos > Python2 > PyMuPDF

comparison mupdf-source/include/mupdf/fitz/story.h @ 2:b50eed0cc0ef upstream

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. The directory name has changed: no version number in the expanded directory now.
author Franz Glasner <fzglas.hg@dom66.de>
date Mon, 15 Sep 2025 11:43:07 +0200
parents
children
comparison
equal deleted inserted replaced
1:1d09e1dec1d9 2:b50eed0cc0ef
1 // Copyright (C) 2004-2025 Artifex Software, Inc.
2 //
3 // This file is part of MuPDF.
4 //
5 // MuPDF is free software: you can redistribute it and/or modify it under the
6 // terms of the GNU Affero General Public License as published by the Free
7 // Software Foundation, either version 3 of the License, or (at your option)
8 // any later version.
9 //
10 // MuPDF is distributed in the hope that it will be useful, but WITHOUT ANY
11 // WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
12 // FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more
13 // details.
14 //
15 // You should have received a copy of the GNU Affero General Public License
16 // along with MuPDF. If not, see <https://www.gnu.org/licenses/agpl-3.0.en.html>
17 //
18 // Alternative licensing terms are available from the licensor.
19 // For commercial licensing, see <https://www.artifex.com/> or contact
20 // Artifex Software, Inc., 39 Mesa Street, Suite 108A, San Francisco,
21 // CA 94129, USA, for further information.
22
23 #ifndef MUPDF_FITZ_STORY_H
24 #define MUPDF_FITZ_STORY_H
25
26 #include "mupdf/fitz/system.h"
27 #include "mupdf/fitz/context.h"
28 #include "mupdf/fitz/buffer.h"
29 #include "mupdf/fitz/device.h"
30 #include "mupdf/fitz/xml.h"
31 #include "mupdf/fitz/archive.h"
32
33 /*
34 This header file provides an API for laying out and placing styled
35 text on a page, or pages.
36
37 First a text story is created from some styled HTML.
38
39 Next, this story can be laid out into a given rectangle (possibly
40 retrying several times with updated rectangles as required).
41
42 Next, the laid out story can be drawn to a given device.
43
44 In the case where the text story cannot be fitted into the given
45 areas all at once, these two steps can be repeated multiple
46 times until the text story is completely consumed.
47
48 Finally, the text story can be dropped in the usual fashion.
49 */
50
51
52 typedef struct fz_story fz_story;
53
54 /*
55 Create a text story using styled html.
56
57 Passing a NULL buffer will be treated as an empty document.
58 Passing a NULL user_css will be treated as an empty CSS string.
59 A non-NULL dir will allow images etc to be loaded. The
60 story keeps its own reference, so the caller can drop its
61 reference after this call.
62 */
63 fz_story *fz_new_story(fz_context *ctx, fz_buffer *buf, const char *user_css, float em, fz_archive *dir);
64
65 /*
66 Retrieve the warnings given from parsing this story.
67
68 If there are warnings, this will be returned as a NULL terminated
69 C string. If there are no warnings, this will return NULL.
70
71 These warnings will not be complete until AFTER any DOM manipulations
72 have been completed.
73
74 This function does not need to be called, but once it has been
75 the DOM is no longer accessible, and any fz_xml pointer
76 retrieved from fz_story_document is no longer valid.
77 */
78 const char *fz_story_warnings(fz_context *ctx, fz_story *story);
79
80 /*
81 Equivalent to fz_place_story_flags with flags being 0.
82 */
83 int fz_place_story(fz_context *ctx, fz_story *story, fz_rect where, fz_rect *filled);
84
85 /*
86 Place (or continue placing) a story into the supplied rectangle
87 'where', updating 'filled' with the actual area that was used.
88 Returns zero (FZ_PLACE_STORY_RETURN_ALL_FITTED) if all the
89 content fitted, non-zero if there is more to fit.
90
91 If the FZ_PLACE_STORY_FLAG_NO_OVERFLOW flag is set, then a
92 return code of FZ_PLACE_STORY_RETURN_OVERFLOW_WIDTH will be
93 returned when the next item (word) to be placed would not fit
94 in a rectangle of that given width.
95
96 Note, that filled may not be returned as a strict subset of
97 where, due to padding/margins at the bottom of pages, and
98 non-wrapping content extending to the right.
99
100 Subsequent calls will attempt to place the same section of story
101 again and again, until the placed story is drawn using fz_draw_story,
102 whereupon subsequent calls to fz_place_story will attempt to place
103 the unused remainder of the story.
104
105 After this function is called, the DOM is no longer accessible,
106 and any fz_xml pointer retrieved from fz_story_document is no
107 longer valid.
108
109 flags: Additional flags controlling layout. Pass 0 if none
110 required.
111 */
112 int fz_place_story_flags(fz_context *ctx, fz_story *story, fz_rect where, fz_rect *filled, int flags);
113
114 enum
115 {
116 /* Avoid the usual HTML behaviour of overflowing the box horizontally
117 * in some circumstances. We now abort the place in such cases and
118 * return with */
119 FZ_PLACE_STORY_FLAG_NO_OVERFLOW = 1,
120
121 /* Specific return codes from fz_place_story_flags. Also
122 * "non-zero" for 'more to fit'. */
123 FZ_PLACE_STORY_RETURN_ALL_FITTED = 0,
124 FZ_PLACE_STORY_RETURN_OVERFLOW_WIDTH = 2
125 };
126
127 /*
128 Draw the placed story to the given device.
129
130 This moves the point at which subsequent calls to fz_place_story
131 will restart placing to the end of what has just been output.
132 */
133 void fz_draw_story(fz_context *ctx, fz_story *story, fz_device *dev, fz_matrix ctm);
134
135 /*
136 Reset the position within the story at which the next layout call
137 will continue to the start of the story.
138 */
139 void fz_reset_story(fz_context *ctx, fz_story *story);
140
141 /*
142 Drop the html story.
143 */
144 void fz_drop_story(fz_context *ctx, fz_story *story);
145
146 /*
147 Get a borrowed reference to the DOM document pointer for this
148 story. Do not destroy this reference, it will be destroyed
149 when the story is laid out.
150
151 This only makes sense before the first placement of the story
152 or retrieval of the warnings. Once either of those things happen
153 the DOM representation is destroyed.
154 */
155 fz_xml *fz_story_document(fz_context *ctx, fz_story *story);
156
157
158 typedef struct
159 {
160 /* The overall depth of this element in the box structure.
161 * This can be used to compare the relative depths of different
162 * elements, but shouldn't be relied upon not to change between
163 * different versions of MuPDF. */
164 int depth;
165
166 /* The heading level of this element. 0 if not a header, or 1-6 for h1-h6. */
167 int heading;
168
169 /* The id for this element. */
170 const char *id;
171
172 /* The href for this element. */
173 const char *href;
174
175 /* The rectangle for this element. */
176 fz_rect rect;
177
178 /* The immediate text for this element. */
179 const char *text;
180
181 /* This indicates whether this opens and/or closes this element.
182 *
183 * As we traverse the tree we do a depth first search. In order for
184 * the caller of fz_story_positions to know whether a given element
185 * is inside another element, we therefore announce 'start' and 'stop'
186 * for each element. For instance, with:
187 *
188 * <div id="part1">
189 * <h1>Chapter 1</h1>...
190 * <h1>Chapter 2</h1>...
191 * ...
192 * </div>
193 * <div id="part2">
194 * <h1>Chapter 10</h1>...
195 * <h1>Chapter 11</h1>...
196 * ...
197 * </div>
198 *
199 * We would announce:
200 * + id='part1' (open)
201 * + header=1 "Chapter 1" (open/close)
202 * + header=1 "Chapter 2" (open/close)
203 * ...
204 * + id='part1' (close)
205 * + id='part2' (open)
206 * + header=1 "Chapter 10" (open/close)
207 * + header=1 "Chapter 11" (open/close)
208 * ...
209 * + id='part2' (close)
210 *
211 * If bit 0 is set, then this 'opens' the element.
212 * If bit 1 is set, then this 'closes' the element.
213 */
214 int open_close;
215
216 /* A count of the number of rectangles that the layout code has split the
217 * story into so far. After the first layout, this will be 1. If a
218 * layout is repeated, this number is not incremented. */
219 int rectangle_num;
220 } fz_story_element_position;
221
222 typedef void (fz_story_position_callback)(fz_context *ctx, void *arg, const fz_story_element_position *);
223
224 /*
225 Enumerate the positions for key blocks in the story.
226
227 This will cause the supplied function to be called with details of each
228 element in the story that is either a header, or has an id.
229 */
230 void fz_story_positions(fz_context *ctx, fz_story *story, fz_story_position_callback *cb, void *arg);
231
232 #endif