Okular

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

KDE's Doxygen guidelines are available online.