Okular

page.h
1/*
2 SPDX-FileCopyrightText: 2004 Enrico Ros <eros.kde@email.it>
3
4 Work sponsored by the LiMux project of the city of Munich:
5 SPDX-FileCopyrightText: 2017 Klarälvdalens Datakonsult AB a KDAB Group company <info@kdab.com>
6
7 SPDX-License-Identifier: GPL-2.0-or-later
8*/
9
10#ifndef _OKULAR_PAGE_H_
11#define _OKULAR_PAGE_H_
12
13#include "area.h"
14#include "global.h"
15#include "okularcore_export.h"
16#include "textpage.h"
17
18class QPixmap;
19
20class PagePainter;
21
22namespace Okular
23{
24class Annotation;
25class Document;
26class DocumentObserver;
27class DocumentPrivate;
28class FormField;
29class PagePrivate;
30class PageTransition;
31class SourceReference;
32class TextSelection;
33class Tile;
34
35/**
36 * @short Collector for all the data belonging to a page.
37 *
38 * The Page class contains pixmaps (referenced using observers id as key),
39 * a search page (a class used internally for retrieving text), rect classes
40 * (that describe links or other active areas in the current page) and more.
41 *
42 * All coordinates are normalized to the page, so {x,y} are valid in [0,1]
43 * range as long as NormalizedRect components.
44 *
45 * Note: The class takes ownership of all objects.
46 */
47class OKULARCORE_EXPORT Page
48{
49public:
50 /**
51 * An action to be executed when particular events happen.
52 */
54 Opening, ///< An action to be executed when the page is "opened".
55 Closing ///< An action to be executed when the page is "closed".
56 };
57
58 /**
59 * Creates a new page.
60 *
61 * @param pageNumber The number of the page in the document.
62 * @param width The width of the page.
63 * @param height The height of the page.
64 * @param orientation The orientation of the page
65 */
66 Page(uint pageNumber, double width, double height, Rotation orientation);
67
68 /**
69 * Destroys the page.
70 */
71 ~Page();
72
73 /**
74 * Returns the number of the page in the document.
75 */
76 int number() const;
77
78 /**
79 * Returns the orientation of the page as defined by the document.
80 */
81 Rotation orientation() const;
82
83 /**
84 * Returns the rotation of the page as defined by the user.
85 */
86 Rotation rotation() const;
87
88 /**
89 * Returns the total orientation which is the original orientation plus
90 * the user defined rotation.
91 */
92 Rotation totalOrientation() const;
93
94 /**
95 * Returns the width of the page.
96 */
97 double width() const;
98
99 /**
100 * Returns the height of the page.
101 */
102 double height() const;
103
104 /**
105 * Returns the ration (height / width) of the page.
106 */
107 double ratio() const;
108
109 /**
110 * Returns the bounding box of the page content in normalized [0,1] coordinates,
111 * in terms of the upright orientation (Rotation0).
112 * If it has not been computed yet, returns the full page (i.e., (0, 0, 1, 1)).
113 * Note that the bounding box may be null if the page is blank.
114 *
115 * @since 0.7 (KDE 4.1)
116 */
117 NormalizedRect boundingBox() const;
118
119 /**
120 * Returns whether the bounding box of the page has been computed.
121 * Note that even if the bounding box is computed, it may be null if the page is blank.
122 *
123 * @since 0.7 (KDE 4.1)
124 */
125 bool isBoundingBoxKnown() const;
126
127 /**
128 * Sets the bounding box of the page content in normalized [0,1] coordinates,
129 * in terms of the upright orientation (Rotation0).
130 * (This does not inform the document's observers, call Document::SetPageBoundingBox
131 * instead if you want that.)
132 *
133 * @since 0.7 (KDE 4.1)
134 */
135 void setBoundingBox(const NormalizedRect &bbox);
136
137 /**
138 * Returns whether the page of size @p width x @p height has a @p pixmap
139 * in the region given by @p rect for the given @p observer
140 * If there is a partially rendered pixmap the answer is false.
141 */
142 bool hasPixmap(DocumentObserver *observer, int width = -1, int height = -1, const NormalizedRect &rect = NormalizedRect()) const;
143
144 /**
145 * Sets the size of the page (in screen pixels) if there is a TilesManager.
146 */
147 void setPageSize(DocumentObserver *observer, int width, int height);
148
149 /**
150 * Returns whether the page provides a text page (@ref TextPage).
151 */
152 bool hasTextPage() const;
153
154 /**
155 * Returns whether the page has an object rect which includes the point (@p x, @p y)
156 * at scale (@p xScale, @p yScale).
157 */
158 bool hasObjectRect(double x, double y, double xScale, double yScale) const;
159
160 /**
161 * Returns whether the page provides highlighting for the observer with the
162 * given @p id.
163 */
164 bool hasHighlights(int id = -1) const;
165
166 /**
167 * Returns whether the page provides a transition effect.
168 */
169 bool hasTransition() const;
170
171 /**
172 * Returns whether the page provides annotations.
173 */
174 bool hasAnnotations() const;
175
176 /**
177 * Returns the bounding rect of the text which matches the following criteria
178 * or 0 if the search is not successful.
179 *
180 * @param id An unique id for this search.
181 * @param text The search text.
182 * @param direction The direction of the search (@ref SearchDirection)
183 * @param caseSensitivity If Qt::CaseSensitive, the search is case sensitive; otherwise
184 * the search is case insensitive.
185 * @param lastRect If 0 (default) the search starts at the beginning of the page, otherwise
186 * right/below the coordinates of the given rect.
187 */
188 RegularAreaRect *findText(int id, const QString &text, SearchDirection direction, Qt::CaseSensitivity caseSensitivity, const RegularAreaRect *lastRect = nullptr) const;
189
190 /**
191 * Returns the page text (or part of it).
192 * @see TextPage::text()
193 */
194 QString text(const RegularAreaRect *area = nullptr) const;
195
196 /**
197 * Returns the page text (or part of it).
198 * @see TextPage::text()
199 * @since 0.10 (KDE 4.4)
200 */
202
203 /**
204 * Returns the page text (or part of it) including the bounding
205 * rectangles. Note that ownership of the contents of the returned
206 * list belongs to the caller.
207 * @see TextPage::words()
208 * @since 0.14 (KDE 4.8)
209 */
211
212 /**
213 * Returns the area and text of the word at the given point
214 * Note that ownership of the returned area belongs to the caller.
215 * @see TextPage::wordAt()
216 * @since 0.15 (KDE 4.9)
217 */
218 std::unique_ptr<RegularAreaRect> wordAt(const NormalizedPoint &p) const;
219
220 /**
221 * Returns the rectangular area of the given @p selection.
222 */
223 std::unique_ptr<RegularAreaRect> textArea(const TextSelection &selection) const;
224
225 /**
226 * Returns the object rect of the given @p type which is at point (@p x, @p y) at scale (@p xScale, @p yScale).
227 */
228 const ObjectRect *objectRect(ObjectRect::ObjectType type, double x, double y, double xScale, double yScale) const;
229
230 /**
231 * Returns all object rects of the given @p type which are at point (@p x, @p y) at scale (@p xScale, @p yScale).
232 * @since 0.16 (KDE 4.10)
233 */
234 QList<const ObjectRect *> objectRects(ObjectRect::ObjectType type, double x, double y, double xScale, double yScale) const;
235
236 /**
237 * Returns the object rect of the given @p type which is nearest to the point (@p x, @p y) at scale (@p xScale, @p yScale).
238 *
239 * @since 0.8.2 (KDE 4.2.2)
240 */
241 const ObjectRect *nearestObjectRect(ObjectRect::ObjectType type, double x, double y, double xScale, double yScale, double *distance) const;
242
243 /**
244 * Returns the transition effect of the page or 0 if no transition
245 * effect is set (see hasTransition()).
246 */
247 const PageTransition *transition() const;
248
249 /**
250 * Returns the list of annotations of the page.
251 */
252 QList<Annotation *> annotations() const;
253
254 /**
255 * Returns the annotation with the given unique name.
256 * @since 1.3
257 */
258 Annotation *annotation(const QString &uniqueName) const;
259
260 /**
261 * Returns the @ref Action object which is associated with the given page @p action
262 * or 0 if no page action is set.
263 */
264 const Action *pageAction(PageAction action) const;
265
266 /**
267 * Returns the list of FormField of the page.
268 */
269 QList<FormField *> formFields() const;
270
271 /**
272 * Sets the region described by @p rect with @p pixmap for the
273 * given @p observer.
274 * If @p rect is not set (default) the @p pixmap is set to the entire
275 * page.
276 */
277 void setPixmap(DocumentObserver *observer, QPixmap *pixmap, const NormalizedRect &rect = NormalizedRect());
278
279 /**
280 * Sets the @p text page.
281 */
282 void setTextPage(TextPage *text);
283
284 /**
285 * Sets the list of object @p rects of the page.
286 */
287 void setObjectRects(const QList<ObjectRect *> &rects);
288
289 /**
290 * Gets the list of object rects of the page.
291 *
292 * @since 22.04
293 */
294 const QList<ObjectRect *> &objectRects() const;
295
296 /**
297 * Sets the list of source reference objects @p rects.
298 */
299 void setSourceReferences(const QList<SourceRefObjectRect *> &rects);
300
301 /**
302 * Sets the duration of the page to @p seconds when displayed in presentation mode.
303 *
304 * Setting a negative number disables the duration.
305 */
306 void setDuration(double seconds);
307
308 /**
309 * Returns the duration in seconds of the page when displayed in presentation mode.
310 *
311 * A negative number means that no time is set.
312 */
313 double duration() const;
314
315 /**
316 * Sets the labels for the page to @p label .
317 */
318 void setLabel(const QString &label);
319
320 /**
321 * Returns the label of the page, or a null string if not set.
322 */
323 QString label() const;
324
325 /**
326 * Returns the current text selection.
327 */
328 const RegularAreaRect *textSelection() const;
329
330 /**
331 * Returns the color of the current text selection, or an invalid color
332 * if no text selection has been set.
333 */
334 QColor textSelectionColor() const;
335
336 /**
337 * Adds a new @p annotation to the page.
338 */
339 void addAnnotation(Annotation *annotation);
340
341 /**
342 * Removes the @p annotation from the page.
343 */
344 bool removeAnnotation(Annotation *annotation);
345
346 /**
347 * Sets the page @p transition effect.
348 */
349 void setTransition(PageTransition *transition);
350
351 /**
352 * Sets the @p link object for the given page @p action.
353 */
354 void setPageAction(PageAction action, Action *link);
355
356 /**
357 * Sets @p fields as list of FormField of the page.
358 */
359 void setFormFields(const QList<FormField *> &fields);
360
361 /**
362 * Deletes the pixmap for the given @p observer
363 */
364 void deletePixmap(DocumentObserver *observer);
365
366 /**
367 * Deletes all pixmaps of the page.
368 */
369 void deletePixmaps();
370
371 /**
372 * Deletes all object rects of the page.
373 */
374 void deleteRects();
375
376 /**
377 * Deletes all source reference objects of the page.
378 */
379 void deleteSourceReferences();
380
381 /**
382 * Deletes all annotations of the page.
383 */
384 void deleteAnnotations();
385
386 /**
387 * Returns whether pixmaps for the tiled observer are handled by a
388 * tile manager.
389 *
390 * @since 0.19 (KDE 4.13)
391 */
392 bool hasTilesManager(const DocumentObserver *observer) const;
393
394 /**
395 * Returns a list of all tiles intersecting with @p rect.
396 *
397 * The list contains only tiles with a pixmap
398 *
399 * @since 0.19 (KDE 4.13)
400 */
401 QList<Tile> tilesAt(const DocumentObserver *observer, const NormalizedRect &rect) const;
402
403private:
404 PagePrivate *d;
405 /// @cond PRIVATE
406 friend class PagePrivate;
407 friend class Document;
408 friend class DocumentPrivate;
409 friend class PixmapRequestPrivate;
410
411 /**
412 * To improve performance PagePainter accesses the following
413 * member variables directly.
414 */
415 friend class ::PagePainter;
416 /// @endcond
417
418 const QPixmap *_o_nearestPixmap(DocumentObserver *, int, int) const;
419
420 QList<ObjectRect *> m_rects;
421 QList<HighlightAreaRect *> m_highlights;
422 QList<Annotation *> m_annotations;
423
424 Q_DISABLE_COPY(Page)
425};
426
427}
428
429#endif
Encapsulates data that describes an action.
Definition action.h:41
Annotation struct holds properties shared by all annotations.
Definition annotations.h:96
Base class for objects being notified when something changes.
Definition observer.h:29
The Document.
Definition document.h:192
NormalizedPoint is a helper class which stores the coordinates of a normalized point.
Definition area.h:117
A NormalizedRect is a rectangle which can be defined by two NormalizedPoints.
Definition area.h:189
An area with normalized coordinates that contains a reference to an object.
Definition area.h:458
ObjectType
Describes the type of storable object.
Definition area.h:463
Information object for the transition effect of a page.
Collector for all the data belonging to a page.
Definition page.h:48
PageAction
An action to be executed when particular events happen.
Definition page.h:53
@ Opening
An action to be executed when the page is "opened".
Definition page.h:54
This is a list of NormalizedRect, to describe an area consisting of multiple rectangles using normali...
Definition area.h:933
Represents the textual information of a Page.
Definition textpage.h:102
TextAreaInclusionBehaviour
Defines the behaviour of adding characters to text() result.
Definition textpage.h:113
Wrapper around the information needed to generate the selection area.
Definition misc.h:19
global.h
Definition action.h:17
Rotation
A rotation.
Definition global.h:46
SearchDirection
Describes the direction of searching.
Definition global.h:36
CaseSensitivity
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri Jun 21 2024 11:54:45 by doxygen 1.10.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.