Mercurial > hgrepos > Python2 > PyMuPDF

comparison mupdf-source/include/mupdf/fitz/outline.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_OUTLINE_H
24 #define MUPDF_FITZ_OUTLINE_H
25
26 #include "mupdf/fitz/system.h"
27 #include "mupdf/fitz/types.h"
28 #include "mupdf/fitz/context.h"
29 #include "mupdf/fitz/link.h"
30 #include "mupdf/fitz/output.h"
31
32 /* Outline */
33
34 typedef struct {
35 char *title;
36 char *uri;
37 int is_open;
38 int flags;
39 float r;
40 float g;
41 float b;
42 } fz_outline_item;
43
44 enum
45 {
46 FZ_OUTLINE_FLAG_BOLD = 1,
47 FZ_OUTLINE_FLAG_ITALIC = 2,
48 };
49
50 typedef struct fz_outline_iterator fz_outline_iterator;
51
52 /**
53 Call to get the current outline item.
54
55 Can return NULL. The item is only valid until the next call.
56 */
57 fz_outline_item *fz_outline_iterator_item(fz_context *ctx, fz_outline_iterator *iter);
58
59 /**
60 Calls to move the iterator position.
61
62 A negative return value means we could not move as requested. Otherwise:
63 0 = the final position has a valid item.
64 1 = not a valid item, but we can insert an item here.
65 */
66 int fz_outline_iterator_next(fz_context *ctx, fz_outline_iterator *iter);
67 int fz_outline_iterator_prev(fz_context *ctx, fz_outline_iterator *iter);
68 int fz_outline_iterator_up(fz_context *ctx, fz_outline_iterator *iter);
69 int fz_outline_iterator_down(fz_context *ctx, fz_outline_iterator *iter);
70
71 /**
72 Call to insert a new item BEFORE the current point.
73
74 Ownership of pointers are retained by the caller. The item data will be copied.
75
76 After an insert, we do not change where we are pointing.
77 The return code is the same as for next, it indicates the current iterator position.
78
79 Note that for PDF documents at least, the is_open field is ignored. All childless
80 nodes are considered closed by PDF, hence (given every newly inserted node is
81 childless by definition) all new nodes are inserted with is_open == false.
82 */
83 int fz_outline_iterator_insert(fz_context *ctx, fz_outline_iterator *iter, fz_outline_item *item);
84
85 /**
86 Delete the current item.
87
88 This implicitly moves us to the 'next' item, and the return code is as for fz_outline_iterator_next.
89 */
90 int fz_outline_iterator_delete(fz_context *ctx, fz_outline_iterator *iter);
91
92 /**
93 Update the current item properties according to the given item.
94 */
95 void fz_outline_iterator_update(fz_context *ctx, fz_outline_iterator *iter, fz_outline_item *item);
96
97 /**
98 Drop the current iterator.
99 */
100 void fz_drop_outline_iterator(fz_context *ctx, fz_outline_iterator *iter);
101
102
103 /** Structure based API */
104
105 /**
106 fz_outline is a tree of the outline of a document (also known
107 as table of contents).
108
109 title: Title of outline item using UTF-8 encoding. May be NULL
110 if the outline item has no text string.
111
112 uri: Destination in the document to be displayed when this
113 outline item is activated. May be an internal or external
114 link, or NULL if the outline item does not have a destination.
115
116 page: The page number of an internal link, or -1 for external
117 links or links with no destination.
118
119 next: The next outline item at the same level as this outline
120 item. May be NULL if no more outline items exist at this level.
121
122 down: The outline items immediate children in the hierarchy.
123 May be NULL if no children exist.
124
125 is_open: If zero, the outline element is closed in the UI. If
126 1, it should be open, showing any child elements.
127
128 flags: Bit 0 set -> Bold, Bit 1 set -> Italic. All other bits
129 reserved.
130
131 r, g, b: The RGB components of the color of this entry.
132 */
133 typedef struct fz_outline
134 {
135 int refs;
136 char *title;
137 char *uri;
138 fz_location page;
139 float x, y;
140 struct fz_outline *next;
141 struct fz_outline *down;
142 unsigned int is_open : 1;
143 unsigned int flags : 7;
144 unsigned int r : 8;
145 unsigned int g : 8;
146 unsigned int b : 8;
147 } fz_outline;
148
149 /**
150 Create a new outline entry with zeroed fields for the caller
151 to fill in.
152 */
153 fz_outline *fz_new_outline(fz_context *ctx);
154
155 /**
156 Increment the reference count. Returns the same pointer.
157
158 Never throws exceptions.
159 */
160 fz_outline *fz_keep_outline(fz_context *ctx, fz_outline *outline);
161
162 /**
163 Decrements the reference count. When the reference point
164 reaches zero, the outline is freed.
165
166 When freed, it will drop linked outline entries (next and down)
167 too, thus a whole outline structure can be dropped by dropping
168 the top entry.
169
170 Never throws exceptions.
171 */
172 void fz_drop_outline(fz_context *ctx, fz_outline *outline);
173
174 /**
175 Routine to implement the old Structure based API from an iterator.
176 */
177 fz_outline *
178 fz_load_outline_from_iterator(fz_context *ctx, fz_outline_iterator *iter);
179
180
181 /**
182 Implementation details.
183 Of use to people coding new document handlers.
184 */
185
186 /**
187 Function type for getting the current item.
188
189 Can return NULL. The item is only valid until the next call.
190 */
191 typedef fz_outline_item *(fz_outline_iterator_item_fn)(fz_context *ctx, fz_outline_iterator *iter);
192
193 /**
194 Function types for moving the iterator position.
195
196 A negative return value means we could not move as requested. Otherwise:
197 0 = the final position has a valid item.
198 1 = not a valid item, but we can insert an item here.
199 */
200 typedef int (fz_outline_iterator_next_fn)(fz_context *ctx, fz_outline_iterator *iter);
201 typedef int (fz_outline_iterator_prev_fn)(fz_context *ctx, fz_outline_iterator *iter);
202 typedef int (fz_outline_iterator_up_fn)(fz_context *ctx, fz_outline_iterator *iter);
203 typedef int (fz_outline_iterator_down_fn)(fz_context *ctx, fz_outline_iterator *iter);
204
205 /**
206 Function type for inserting a new item BEFORE the current point.
207
208 Ownership of pointers are retained by the caller. The item data will be copied.
209
210 After an insert, we implicitly do a next, so that a successive insert operation
211 would insert after the item inserted here. The return code is therefore as for next.
212 */
213 typedef int (fz_outline_iterator_insert_fn)(fz_context *ctx, fz_outline_iterator *iter, fz_outline_item *item);
214
215 /**
216 Function type for deleting the current item.
217
218 This implicitly moves us to the 'next' item, and the return code is as for fz_outline_iterator_next.
219 */
220 typedef int (fz_outline_iterator_delete_fn)(fz_context *ctx, fz_outline_iterator *iter);
221
222 /**
223 Function type for updating the current item properties according to the given item.
224 */
225 typedef void (fz_outline_iterator_update_fn)(fz_context *ctx, fz_outline_iterator *iter, fz_outline_item *item);
226
227 /**
228 Function type for dropping the current iterator.
229 */
230 typedef void (fz_outline_iterator_drop_fn)(fz_context *ctx, fz_outline_iterator *iter);
231
232 #define fz_new_derived_outline_iter(CTX, TYPE, DOC)\
233 ((TYPE *)Memento_label(fz_new_outline_iterator_of_size(ctx,sizeof(TYPE),DOC),#TYPE))
234
235 fz_outline_iterator *fz_new_outline_iterator_of_size(fz_context *ctx, size_t size, fz_document *doc);
236
237 fz_outline_iterator *fz_outline_iterator_from_outline(fz_context *ctx, fz_outline *outline);
238
239 struct fz_outline_iterator {
240 /* Functions */
241 fz_outline_iterator_drop_fn *drop;
242 fz_outline_iterator_item_fn *item;
243 fz_outline_iterator_next_fn *next;
244 fz_outline_iterator_prev_fn *prev;
245 fz_outline_iterator_up_fn *up;
246 fz_outline_iterator_down_fn *down;
247 fz_outline_iterator_insert_fn *insert;
248 fz_outline_iterator_update_fn *update;
249 fz_outline_iterator_delete_fn *del;
250 /* Common state */
251 fz_document *doc;
252 };
253
254 #endif