summaryrefslogtreecommitdiffstats
path: root/kviewshell/renderedDocumentPage.h
blob: a266188ab1af731b20788c1f364ea4e1e4bce254 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
// -*- C++ -*-
//
// Class: documentPage
//
// Widget for displaying TeX DVI files.
// Part of KDVI- A previewer for TeX DVI files.
//
// (C) 2004-2005 Stefan Kebekus. Distributed under the GPL.


#ifndef _rendereddocumentpage_h_
#define _rendereddocumentpage_h_

#include "pageNumber.h"

#include <tqobject.h>
#include <tqstring.h>
#include <tqvaluevector.h>

class Hyperlink;
class TQPainter;
class TQRect;
class TQRegion;
class TextBox;
class TextSelection;

/** @short Represents a page in a document, contains the page's graphical
    representation and resolution-dependent information.

    This abstract class represents a page in a document. Its
    implementations contain graphical representations of document pages,
    and resolution-dependent information. The most important members are

    - the page number

    - a vector that contains hyperlinks

    - a vector for source hyperlinks; this vector is currently used by
      KDVI only, and is therefore not documented much here.

    - a vector that contains the document text together with
    information about the position of the text on the page. This
    information is used in kviewshell e.g. for selecting text with the
    mouse or for the "export as text..." functionality

    - the implementations of the documentPage will also contain a
    TQPaintDevice, onto which the graphical representation of the page
    is rendered. This could for instance be a TQPixmap, if the page is
    to be displayed on a computer screen, or a TQPrinter for printing.

    The kviewshell program uses the documentPage class in the
    following manner: first, it is constructed, the page number is
    invalid. The page number is then set to a reasonable value using
    the setPageNumber() method. After this, the
    documentRenderer.drawPage() method of an implementation of the
    documentRenderer is used to render a graphical representation into
    the TQPaintDevice at a given resolution, and to fill the
    (source-)hyperlink and text vectors, which are also
    resolution-dependent. After the data has been used, the
    documentPage is clear()ed, perhaps a new page number set, and
    documentRenderer.drawPage() is used again.

    @author Stefan Kebekus <kebekus@kde.org>
    @version 1.0.0
*/

class RenderedDocumentPage : public TQObject
{
  Q_OBJECT
  

 public:
  /** \brief Default constructor

  The default constructor constructs a RenderedDocumentPage whose pageNumber
  is invalid. It sets the member 'isEmpty' to 'true'.
  */
  RenderedDocumentPage();

  virtual ~RenderedDocumentPage();

  /** \brief Set page number

  This method sets the number of the page that this instance
  represents. A value of '0' means that this class does not represent
  any page ('invalid page'). This method also calls clear().
  */
  void setPageNumber(const PageNumber& pagenr);

  /** \brief Get page number

  @returns The number of the page that this instance represents.
  */
  PageNumber getPageNumber() const {return pageNr;}

  /** \brief Get paint device

  This method is used for instance by the documentRenderer.drawPage()
  method to draw on the page. It returns a pointer to a TQPainter (in
  most implementation a painter on either a TQPixmap, or a
  TQPrinter). The pointer returned points to an active TQPainter and is
  valid as long as *this RenderedDocumentPage exists. The pointer
  returned must not be deleted nor should TQPainter::end() be
  called. Instead, the method returnPainter() must be called as soon
  as drawing is finished.

  In short, to draw on a renderedDocumentPage, you do the following:
  @code
  RenderedDocumentPage rdp;

  TQPainter *paint = rdp.getPainter()
  if (paint != 0) {
  
    <Do some painting, don't call paint->end() >
  
    rdp.returnPainter(paint);
  }
  @endcode

  @warning Before the pointer has been returned by the returnPainter()
  method, all subsequent calls to getPainter() will return undefined
  results. Do not delete a renderedDocumentPage when you still hold a
  pointer. Call returnPainter() first.

  @returns A pointer to a TQPainter (in most implementation a painter
  on either a TQPixmap, or a TQPrinter), or NULL, if painting is not
  possible. The TQPainter object is owned by the RenderedDocumentPage.
  */
  virtual TQPainter *getPainter() = 0;

  
  /** \brief Returns a pointer to the paint device.

  See the documentation to the getPainter() method for an explanation

  @see getPainter
  
  @warning Returning a pointer twice, or returning arbitrary pointers
  will lead to a segfault.

  @param pt a pointer to a TQPainter, as returned by the getPainter()
  method
  */
  virtual void returnPainter(TQPainter *pt) = 0;
  
  /** \brief Returns the size of the page in pixel. */
  virtual TQSize size() = 0;

  /** \brief Returns the width of the page in pixel.

  @warning If you are implementing DocumentRenderer::drawPage(), it
  may be tempting to compute the image size in pixel, using
  page->height() and page->width(). DON'T DO THAT. KViewShell uses
  transformations e.g. to rotate the page, and sets the argument
  'resolution' accordingly; these changes are not reflected in
  page->height() and page->width(). Similar problems occur if
  KViewShell required a shrunken version of the page, e.g. to print
  multiple pages on one sheet of paper. See the documentation of
  DocumentRenderer::drawPage() to learn how to compute the sizes
  properly.
  */
  virtual int width() {return size().width(); }

  /** \brief Returns the height of the page in pixel. 

  @warning If you are implementing DocumentRenderer::drawPage(), it
  may be tempting to compute the image size in pixel, using
  page->height() and page->width(). DON'T DO THAT. KViewShell uses
  transformations e.g. to rotate the page, and sets the argument
  'resolution' accordingly; these changes are not reflected in
  page->height() and page->width(). Similar problems occur if
  KViewShell required a shrunken version of the page, e.g. to print
  multiple pages on one sheet of paper. See the documentation of
  DocumentRenderer::drawPage() to learn how to compute the sizes
  properly.
  */
  virtual int height() {return size().height(); }

  /** \brief Text contained in the document page
      
  This vector contains the document text together with information
  about the position of the text on the page. This information is
  generated by the documentRenderer.drawPage() method. It is used in
  kviewshell e.g. for selecting text with the mouse or for the "export
  as text..." functionality.
  */
  TQValueVector<TextBox> textBoxList;

  /** \brief Calculates the text selected by the given rectangle. */
  TextSelection select(const TQRect&);

  /** \brief Selects the character which lies at the given point. */
  TextSelection select(const TQPoint&);

  TQRegion selectedRegion(const TextSelection& selection);

  /** Finds the first occurence of str starting by the current index.
  If the text is found a corresponding TextSelection is returned.
  If the text is not found a empty selection is returned. */
  TextSelection find(const TQString& str, int index = 0, bool caseSensitive = true);

  /** Finds the first occurence of str starting by the current index searching backwards.
  If the text is found a corresponding TextSelection is returned.
  If the text is not found a empty selection is returned.
  If index < 0 start the search at the end of the page. */
  TextSelection findRev(const TQString& str, int index = 0, bool cs = true);

  /** \brief Hyperlinks on the document page

  This vector contains the hyperlinks that appear on the page. This
  information is generated by the documentRenderer.drawPage()
  method. It is used in kviewshell so users can use the mouse to
  navigate in the document through hyperlinks.
  */
  TQValueVector<Hyperlink> hyperLinkList;

  // set to 'false' in the constructor, set to 'true' by the renderer,
  // if something really has been rendered
  bool isEmpty;

  /** \brief Clears the data structures
      
  Clears the contents of the class, but leaves pageNumber intact. For
  performance reasons, it does not free the memory for the
  TQValueVectors so that lengthy re-allocations won't be necessary
  later.
  */
  virtual void clear();
  
 private:
  /** \brief Page number

  Number of the page that this instance represents a value of '0'
  means that this class does not represent any page.
  */
  PageNumber  pageNr;

  TQString pageText;
};


#endif