Changeset View
Standalone View
core/area.h
Show All 26 Lines | |||||
27 | namespace Okular { | 27 | namespace Okular { | ||
28 | 28 | | |||
29 | class Annotation; | 29 | class Annotation; | ||
30 | class Action; | 30 | class Action; | ||
31 | class NormalizedShape; | 31 | class NormalizedShape; | ||
32 | 32 | | |||
33 | /** | 33 | /** | ||
34 | * NormalizedPoint is a helper class which stores the coordinates | 34 | * NormalizedPoint is a helper class which stores the coordinates | ||
35 | * of a normalized point. Normalized means that the coordinates are | 35 | * of a normalized point. | ||
aacid: i don't see why your version of the text is better. | |||||
Not sure. Shall I change it back? The paragraph “Coordinate System” should make it clear anyway. davidhurka: Not sure. Shall I change it back?
The paragraph “Coordinate System” should make it clear… | |||||
36 | * between 0 and 1 so that it is page size independent. | | |||
37 | * | 36 | * | ||
38 | * Example: | 37 | * @par Normalized Coordinate System | ||
39 | * The normalized point is (0.5, 0.3) | 38 | * @parblock | ||
40 | * | 39 | * Normalized means that the coordinates are always between 0 and 1, | ||
41 | * If you want to draw it on a 800x600 page, just multiply the x coordinate (0.5) with | 40 | * unless the point shall be outside of the reference area. | ||
42 | * the page width (800) and the y coordinate (0.3) with the page height (600), so | 41 | * | ||
43 | * the point will be drawn on the page at (400, 180). | 42 | * The reference area is a rectangle, and all normalized points | ||
43 | * with coordinates of 0 or 1 describe its edges. | ||||
44 | * | ||||
45 | * This allows to locate things on a reference area without knowing its | ||||
46 | * (current or future) actual size. When the reference area is resized, | ||||
47 | * all things which are described in normalized coordinates keep their | ||||
48 | * proportional position on the area. | ||||
49 | * @endparblock | ||||
50 | * | ||||
51 | * @par Transformation to and from Normalized Coordinates | ||||
52 | * @parblock | ||||
53 | * To transform normalized coordinates to coordinates on the reference area, | ||||
54 | * just multiply them with the size of the reference area. | ||||
55 | * | ||||
56 | * To get normalized coordinates from a point on the reference area, | ||||
57 | * just divide its coordinates with the size of the reference area. | ||||
58 | * | ||||
59 | * Many methods have parameters @c xScale and @c yScale, | ||||
60 | * these are equal to the size of the reference area. | ||||
61 | * @endparblock | ||||
aacid: recarding typeo | |||||
62 | * | ||||
63 | * @par Normalized Coordinate System Applied to Pages | ||||
64 | * @parblock | ||||
65 | * Okular uses a normalized coordinate system mainly to describe | ||||
66 | * positions on pages. | ||||
67 | * This is useful because pages can be shown in different sizes (zoom), | ||||
68 | * but all objects shall keep their proportional position on the page. | ||||
69 | * | ||||
70 | * Okular maps from page to normalized coordinates as follows: | ||||
71 | * * Left edge of the page: x = 0 | ||||
72 | * * Right edge of the page: x = 1 | ||||
73 | * * Top edge of the page: y = 0 | ||||
74 | * * Bottom edge of the page: y = 1 | ||||
75 | * @endparblock | ||||
76 | * | ||||
77 | * @par Example: Draw a Point on a Page | ||||
78 | * @parblock | ||||
79 | * The point is given in normalized coordinates (0.5, 0.3). | ||||
80 | * | ||||
81 | * If you want to draw it on a 800x600 page, | ||||
82 | * just multiply the x coordinate (0.5) with the page width (800), | ||||
83 | * and the y coordinate (0.3) with the page height (600). | ||||
84 | * So, the point will be drawn on the page at (400, 180). | ||||
44 | * | 85 | * | ||
45 | * That allows you to zoom the page by just multiplying the normalized points with the | 86 | * That allows you to zoom the page by just multiplying the normalized points with the | ||
46 | * zoomed page size. | 87 | * zoomed page size. | ||
88 | * @endparblock | ||||
89 | * | ||||
90 | * @par Example: Select Text on a Page using Mouse Events | ||||
91 | * @parblock | ||||
92 | * The positon of all glyphs and words is stored in normalized coordinates. | ||||
93 | * (This is what TextPage actually does.) | ||||
94 | * Mouse click and release events are given in page coordinates (400, 180) and (600, 450), | ||||
aacid: click->press | |||||
95 | * while the page has a size of 800x600. | ||||
96 | * | ||||
97 | * If you want to seach all text between the mouse click and release event, | ||||
aacid: seach -> search, click -> press | |||||
98 | * you need their normalized coordinates. | ||||
99 | * Just divide the x coordinates (400 and 600) by the page width (800), | ||||
100 | * and the y coordinates (180 and 450) by the page height (600). | ||||
101 | * So, you have to search for all glyphs between (0.5, 0.3) and (0.75, 0.75). | ||||
102 | * | ||||
103 | * That allows you to process all glyphs and words without | ||||
104 | * having to keep any of their positions in sync with the page. | ||||
105 | * @endparblock | ||||
106 | * | ||||
107 | * @par Geometric operations | ||||
108 | * @parblock | ||||
109 | * NormalizedPoint supports basic geometric operations. | ||||
110 | * * You can transform it with a QTransform matrix. | ||||
111 | * * With the size of the reference area, you can calculate the squared | ||||
112 | * absolute distance to another NormalizedPoint or a line of two NormalizedPoints. | ||||
113 | * | ||||
114 | * NormalizedRect provides additional geometric operations for rectangles. | ||||
115 | * @endparblock | ||||
116 | * | ||||
117 | * @see NormalizedRect | ||||
aacid: zoom doesn't seem the appropiate word here, there's no zooming involved | |||||
davidhurka: Hmm, agreed. Will change it back. | |||||
47 | */ | 118 | */ | ||
48 | class OKULARCORE_EXPORT NormalizedPoint | 119 | class OKULARCORE_EXPORT NormalizedPoint | ||
49 | { | 120 | { | ||
50 | public: | 121 | public: | ||
51 | /** | 122 | /** | ||
52 | * Creates a new empty normalized point. | 123 | * Creates a normalized point at (0, 0). | ||
aacid: why "the" ? | |||||
I thought that all instances will be equal points, so “the” would be appropiate. Usually it goes “creates a null ...”, so “a” is probaby better. BTW: There is no NormalizedPoint::isNull(), so why this constructor? davidhurka: I thought that all instances will be equal points, so “the” would be appropiate.
Usually it… | |||||
53 | */ | 124 | */ | ||
54 | NormalizedPoint(); | 125 | NormalizedPoint(); | ||
55 | 126 | | |||
56 | /** | 127 | /** | ||
57 | * Creates a new normalized point with the normalized coordinates (@p x, @p y ). | 128 | * Creates a new normalized point with the normalized coordinates (@p x, @p y ). | ||
58 | */ | 129 | */ | ||
59 | NormalizedPoint( double x, double y ); | 130 | NormalizedPoint( double x, double y ); | ||
60 | 131 | | |||
61 | /** | 132 | /** | ||
62 | * Creates a new normalized point with the coordinates (@p x, @p y) which are normalized | 133 | * Creates a new normalized point from an absolute point (@p x, @p y) | ||
63 | * by the scaling factors @p xScale and @p yScale. | 134 | * on a reference area of size @p xScale x @p yScale. | ||
aacid: I don't like that you mention a page here. | |||||
One can scale with a factor or with a divisor, and will probaby call both scaling factor. So what should xScale or yScale be? I think saying “page size” makes it clear. Using a PageSize or ScalingFactor struct would make it clear as well. davidhurka: One can scale with a factor or with a divisor, and will probaby call both scaling //factor//. | |||||
64 | */ | 135 | */ | ||
65 | NormalizedPoint( int x, int y, int xScale, int yScale ); | 136 | NormalizedPoint( int x, int y, int xScale, int yScale ); | ||
66 | 137 | | |||
67 | /** | 138 | /** | ||
68 | * @internal | 139 | * @internal | ||
69 | */ | 140 | */ | ||
70 | NormalizedPoint& operator=( const NormalizedPoint& ); | 141 | NormalizedPoint& operator=( const NormalizedPoint& ); | ||
71 | 142 | | |||
72 | NormalizedPoint( const NormalizedPoint& ); | 143 | NormalizedPoint( const NormalizedPoint& ); | ||
73 | ~NormalizedPoint(); | 144 | ~NormalizedPoint(); | ||
74 | 145 | | |||
75 | /** | 146 | /** | ||
76 | * Transforms the normalized point with the operations defined by @p matrix. | 147 | * Transforms the normalized point with the operations defined by @p matrix. | ||
77 | */ | 148 | */ | ||
78 | void transform( const QTransform &matrix ); | 149 | void transform( const QTransform &matrix ); | ||
79 | 150 | | |||
80 | /** | 151 | /** | ||
81 | * Returns squared distance to point @p x @p y @p xScale @p yScale | 152 | * Returns squared distance to normalized point (@p x, @p y) | ||
153 | * on a reference area of size @p xScale x @p yScale. | ||||
aacid: same, this is not striclty page related | |||||
I think in this case it is strictly page size related, because it unifies vertical and horizontal distance using Phytagoras. Without the page size, the result would be meaningless in many cases. Besides that, NormalizedPoint classes could be used as abstract coordinate system convenience classes, for anything else with varying absolute sizes. Can we expect anything else than pages? If you wish to keep the documemtation compatible to future use cases, I could just clarify the scaling. Examle: * @par Scaling * To convert a NormalizedPoint to a point with absolute coordinates, * the normalized coordinate system needs to be mapped to the reference area. * This can be done with two scaling factors, xScale and yScale. * These will just be equal to the width and height of the reference area. * davidhurka: I think in this case it is strictly page //size// related, because it unifies vertical and… | |||||
It is not page size related *at all* It's just two points, one of them has a scaling. Nothing here is necessarily about pages. aacid: It is not page size related *at all*
It's just two points, one of them has a scaling. Nothing… | |||||
82 | * @since 0.17 (KDE 4.11) | 154 | * @since 0.17 (KDE 4.11) | ||
83 | */ | 155 | */ | ||
84 | double distanceSqr( double x, double y, double xScale, double yScale ) const; | 156 | double distanceSqr( double x, double y, double xScale, double yScale ) const; | ||
85 | 157 | | |||
86 | | ||||
87 | /** | 158 | /** | ||
88 | * @brief Calculates distance of the point @p x @p y @p xScale @p yScale to the line segment from @p start to @p end | 159 | * Returns squared distance of the normalized point (@p x, @p y) | ||
160 | * to the line segment from @p start to @p end | ||||
161 | * on a reference area of size @p xScale x @p yScale. | ||||
89 | * @since 0.17 (KDE 4.11) | 162 | * @since 0.17 (KDE 4.11) | ||
90 | */ | 163 | */ | ||
91 | static double distanceSqr( double x, double y, double xScale, double yScale, const NormalizedPoint& start, const NormalizedPoint& end ); | 164 | static double distanceSqr( double x, double y, double xScale, double yScale, const NormalizedPoint& start, const NormalizedPoint& end ); | ||
davidhurka: Is there a reason to make this one function `static`? | |||||
i don't know, you may want to ask Peter, but it was 6 years ago, i doubt he remembers. What's your problem with it being static? aacid: i don't know, you may want to ask Peter, but it was 6 years ago, i doubt he remembers.
What's… | |||||
It would make sense to make it non static, because the first parameter is a NormalizedPoint (consists of x and y, xScale and yScale don’t scale the point). Anyway, OKULARCORE_EXPORT is a reason to keep it static, right? davidhurka: It would make sense to make it non static, because the first parameter is a NormalizedPoint… | |||||
it's exported api, so yes let's not change it, and less in a "improve documentation" MR ;) aacid: it's exported api, so yes let's not change it, and less in a "improve documentation" MR ;) | |||||
92 | 165 | | |||
93 | /** | 166 | /** | ||
94 | * The normalized x coordinate. | 167 | * The normalized x coordinate. | ||
95 | */ | 168 | */ | ||
96 | double x; | 169 | double x; | ||
97 | 170 | | |||
98 | /** | 171 | /** | ||
99 | * The normalized y coordinate. | 172 | * The normalized y coordinate. | ||
100 | */ | 173 | */ | ||
101 | double y; | 174 | double y; | ||
102 | }; | 175 | }; | ||
103 | 176 | | |||
104 | 177 | | |||
105 | /** | 178 | /** | ||
106 | * NormalizedRect is a helper class which stores the coordinates | 179 | * A NormalizedRect is a rectangle which can be defined by two NormalizedPoints. | ||
107 | * of a normalized rect, which is a rectangle of @see NormalizedPoints. | 180 | * | ||
181 | * It describes a rectangular area on a reference area of undefined size. | ||||
Again this is not strictly page related, can be used for anything please don't refer to pages other than as "for example" aacid: Again this is not strictly page related, can be used for anything please don't refer to pages… | |||||
182 | * For more information about the normalized coordinate system, see NormalizedPoint. | ||||
183 | * | ||||
184 | * In Okular, NormalizedRect is used to describe bounding boxes of TextEntity objects, | ||||
aacid: This information makes no sense here. | |||||
TextEntity provides example usage, so someone who wonders why this class exists will be happy. Throwing in this link, because it mentions examples. I will remove the “glyphs, words, line...”, that’s too specific. davidhurka: TextEntity provides example usage, so someone who wonders why this class exists will be happy. | |||||
i still don't like the "is used" wording, it's like binds it forever, if you really want to reference a class (can't people use grep or find all in an IDE), i'd prefer a wording like "for example is used in" or similar aacid: i still don't like the "is used" wording, it's like binds it forever, if you really want to… | |||||
davidhurka: is used -> can be used e. g.
Better? | |||||
185 | * and the highlight area of text selections. | ||||
186 | * | ||||
187 | * If you need to describe an area which consists of multiple rectangles, | ||||
What a regularAreaRect is doesn't belong to the description of NormalizedRect (imho, the @see is fine) aacid: What a regularAreaRect is doesn't belong to the description of NormalizedRect (imho, the @see… | |||||
It provides an alternative to NormalizedRect. NormalizedRect is already pretty good for describing shapes on a page, but in some cases RegularAreaRect will be better. davidhurka: It provides an alternative to NormalizedRect. NormalizedRect is already pretty good for… | |||||
188 | * you can use RegularAreaRect instead. | ||||
189 | * | ||||
190 | * @see NormalizedPoint, RegularAreaRect, TextEntity | ||||
108 | */ | 191 | */ | ||
109 | class OKULARCORE_EXPORT NormalizedRect | 192 | class OKULARCORE_EXPORT NormalizedRect | ||
110 | { | 193 | { | ||
111 | public: | 194 | public: | ||
112 | /** | 195 | /** | ||
113 | * Creates a null normalized rectangle. | 196 | * Creates a null normalized rectangle. | ||
114 | * @see isNull() | 197 | * @see isNull() | ||
115 | */ | 198 | */ | ||
116 | NormalizedRect(); | 199 | NormalizedRect(); | ||
117 | 200 | | |||
118 | /** | 201 | /** | ||
119 | * Creates a normalized rectangle with the normalized coordinates | 202 | * Creates a normalized rectangle with the normalized coordinates | ||
120 | * @p left, @p top, @p right, @p bottom. | 203 | * @p left, @p top, @p right, @p bottom. | ||
121 | * | 204 | * | ||
122 | * If you need the x, y, width and height coordinates use the | 205 | * If you need the x, y, width and height coordinates use the | ||
123 | * following formulas: | 206 | * following formulas: | ||
124 | * | 207 | * | ||
125 | * @li x = left | 208 | * @li x = left | ||
126 | * @li y = top | 209 | * @li y = top | ||
127 | * @li width = right - left | 210 | * @li width = right - left | ||
128 | * @li height = bottom - top | 211 | * @li height = bottom - top | ||
212 | * | ||||
213 | * @note | ||||
214 | * The coordinates for @p left and @p top must be lower than | ||||
what if they want it to be negative for some reason? Does anything break? i mean the lines above clearly say left, top, and bottom. aacid: what if they want it to be negative for some reason? Does anything break? i mean the lines… | |||||
Yes, e. g. if left is right of right, the geometry operations (|=, &=, etc) don’t behave really ...obviously defined. It will probably work, but it might work differently as soon as someone tries to fix a bug. The problem is mainly that the behaviour will not be defined even after this patch, so I simply write it this way. davidhurka: Yes, e. g. if `left` is right of `right`, the geometry operations (|=, &=, etc) don’t behave… | |||||
215 | * @p right and @p bottom, respectively, to avoid negative width or height. | ||||
129 | */ | 216 | */ | ||
130 | NormalizedRect( double left, double top, double right, double bottom ); | 217 | NormalizedRect( double left, double top, double right, double bottom ); | ||
131 | 218 | | |||
132 | /** | 219 | /** | ||
133 | * Creates a normalized rectangle of the given @p rectangle which is normalized | 220 | * Creates a normalized rectangle from the given @p rectangle | ||
134 | * by the scaling factors @p xScale and @p yScale. | 221 | * on a reference area of size @p xScale x @p yScale. | ||
222 | * | ||||
223 | * @note | ||||
224 | * The rectangle must have positive width and height. | ||||
aacid: same as above, does it really need to have a positive width and height? | |||||
davidhurka: Added a sloppy note why it should be positive. | |||||
225 | * You can use e. g. QRect::normalize() to ensure this. | ||||
135 | */ | 226 | */ | ||
136 | NormalizedRect( const QRect &rectangle, double xScale, double yScale ); | 227 | NormalizedRect( const QRect &rectangle, double xScale, double yScale ); | ||
137 | 228 | | |||
138 | /** | 229 | /** | ||
139 | * @internal | 230 | * @internal | ||
140 | */ | 231 | */ | ||
141 | NormalizedRect( const NormalizedRect& ); | 232 | NormalizedRect( const NormalizedRect& ); | ||
142 | 233 | | |||
143 | /** | 234 | /** | ||
144 | * @internal | 235 | * @internal | ||
145 | */ | 236 | */ | ||
146 | NormalizedRect& operator=( const NormalizedRect &other ); | 237 | NormalizedRect& operator=( const NormalizedRect &other ); | ||
147 | 238 | | |||
148 | ~NormalizedRect(); | 239 | ~NormalizedRect(); | ||
149 | 240 | | |||
150 | /** | 241 | /** | ||
151 | * Build a normalized rect from a QRectF. | 242 | * Build a normalized rect from a QRectF, which already has normalized coordinates. | ||
152 | */ | 243 | */ | ||
153 | static NormalizedRect fromQRectF( const QRectF &rect ); | 244 | static NormalizedRect fromQRectF( const QRectF &rect ); | ||
154 | 245 | | |||
155 | /** | 246 | /** | ||
156 | * Returns whether this normalized rectangle is a null normalized rect. | 247 | * Returns whether this normalized rectangle is a null normalized rect. | ||
157 | */ | 248 | */ | ||
158 | bool isNull() const; | 249 | bool isNull() const; | ||
This is implemented with double == 0. Won’t this always return true? bool NormalizedRect::isNull() const { return left == 0 && top== 0 && right == 0 && bottom == 0; } davidhurka: This is implemented with double == 0. Won’t this always return true?
```
bool NormalizedRect… | |||||
Why would it always return true? When left is 0.5 it will obviously return false, no? aacid: Why would it always return true?
When left is 0.5 it will obviously return false, no? | |||||
You’re right, I thought this converts to int, tuncating the value, but it will convert to double. davidhurka: You’re right, I thought this converts to int, tuncating the value, but it will convert to… | |||||
159 | 250 | | |||
160 | /** | 251 | /** | ||
161 | * Returns whether the normalized rectangle contains the normalized coordinates | 252 | * Returns whether the normalized rectangle contains the normalized point | ||
162 | * @p x and @p y. | 253 | * (@p x, @p y). | ||
163 | */ | 254 | */ | ||
164 | bool contains( double x, double y ) const; | 255 | bool contains( double x, double y ) const; | ||
165 | 256 | | |||
166 | /** | 257 | /** | ||
167 | * Returns whether the normalized rectangle intersects the @p other normalized | 258 | * Returns whether the normalized rectangle intersects the @p other normalized | ||
168 | * rectangle. | 259 | * rectangle. | ||
169 | */ | 260 | */ | ||
170 | bool intersects( const NormalizedRect &other ) const; | 261 | bool intersects( const NormalizedRect &other ) const; | ||
171 | 262 | | |||
172 | /** | 263 | /** | ||
173 | * This is an overloaded member function, provided for convenience. It behaves essentially | 264 | * This is an overloaded member function, provided for convenience. It behaves essentially | ||
174 | * like the above function. | 265 | * like the above function. | ||
175 | */ | 266 | */ | ||
176 | bool intersects( const NormalizedRect *other ) const; | 267 | bool intersects( const NormalizedRect *other ) const; | ||
177 | 268 | | |||
178 | /** | 269 | /** | ||
179 | * Returns whether the normalized rectangle intersects an other normalized | 270 | * Returns whether the normalized rectangle intersects an other normalized | ||
180 | * rectangle, which is defined by @p left, @p top, @p right and @p bottom. | 271 | * rectangle, which is defined by @p left, @p top, @p right and @p bottom. | ||
181 | */ | 272 | */ | ||
182 | bool intersects( double left, double top, double right, double bottom ) const; | 273 | bool intersects( double left, double top, double right, double bottom ) const; | ||
183 | 274 | | |||
184 | /** | 275 | /** | ||
185 | * Returns the rectangle that accrues when the normalized rectangle is multiplyed | 276 | * Returns the rectangle mapped to a reference area of @p xScale x @p yScale. | ||
186 | * with the scaling @p xScale and @p yScale. | | |||
187 | */ | 277 | */ | ||
188 | QRect geometry( int xScale, int yScale ) const; | 278 | QRect geometry( int xScale, int yScale ) const; | ||
189 | 279 | | |||
190 | /** | 280 | /** | ||
191 | * Same functionality as geometry, but the output is now rounded before typecasting to int | 281 | * Same functionality as geometry, but the output is now rounded before typecasting to int | ||
282 | * | ||||
192 | * @since 0.14 (KDE 4.8) | 283 | * @since 0.14 (KDE 4.8) | ||
193 | */ | 284 | */ | ||
194 | QRect roundedGeometry( int xScale, int yScale ) const; | 285 | QRect roundedGeometry( int xScale, int yScale ) const; | ||
What’s the purpose of rounding? The application code looks like it doesn’t matter. davidhurka: What’s the purpose of rounding? The application code looks like it doesn’t matter. | |||||
I don't understand the question. The purpose it is "it's rounded and thus potentially more accurate than without rounding because 0.9 will be 1 instead of 0"? i mean it's like you're asking "what is rounding"? aacid: I don't understand the question. The purpose it is "it's rounded and thus potentially more… | |||||
Rounding is like a statistical offset of 0.5. davidhurka: Rounding is like a statistical offset of 0.5.
And in the application (TextEntity… | |||||
195 | 286 | | |||
196 | /** | 287 | /** | ||
197 | * Returns the normalized bounding rectangle of the normalized rectangle | 288 | * Returns the normalized bounding rectangle of the normalized rectangle | ||
198 | * combined with the @p other normalized rectangle. | 289 | * combined with the @p other normalized rectangle. | ||
199 | */ | 290 | */ | ||
200 | NormalizedRect operator|( const NormalizedRect &other ) const; | 291 | NormalizedRect operator|( const NormalizedRect &other ) const; | ||
201 | 292 | | |||
202 | /** | 293 | /** | ||
203 | * Sets the normalized rectangle to the normalized bounding rectangle | 294 | * Sets the normalized rectangle to the normalized bounding rectangle | ||
204 | * of itself combined with the @p other normalized rectangle. | 295 | * of itself combined with the @p other normalized rectangle. | ||
205 | */ | 296 | */ | ||
206 | NormalizedRect& operator|=( const NormalizedRect &other ); | 297 | NormalizedRect& operator|=( const NormalizedRect &other ); | ||
207 | 298 | | |||
208 | /** | 299 | /** | ||
209 | * Returns the intersection of this normalized rectangle with the specified | 300 | * Returns the intersection of this normalized rectangle with the specified | ||
210 | * @p other. If the rects do not intersect then the result is null. | 301 | * @p other. If the rects do not intersect then the result is a null rectangle. | ||
211 | * | 302 | * | ||
212 | * @since 0.7 (KDE 4.1) | 303 | * @since 0.7 (KDE 4.1) | ||
213 | */ | 304 | */ | ||
214 | NormalizedRect operator&( const NormalizedRect &other ) const; | 305 | NormalizedRect operator&( const NormalizedRect &other ) const; | ||
215 | 306 | | |||
216 | /** | 307 | /** | ||
217 | * Returns whether the normalized rectangle is equal to the @p other | 308 | * Returns whether the normalized rectangle is equal to the @p other | ||
218 | * normalized rectangle. | 309 | * normalized rectangle. | ||
219 | */ | 310 | */ | ||
220 | bool operator==( const NormalizedRect &other ) const; | 311 | bool operator==( const NormalizedRect &other ) const; | ||
221 | 312 | | |||
222 | /** | 313 | /** | ||
223 | * Returns the center of the rectangle | 314 | * Returns the center of the rectangle | ||
224 | * @since 0.10 (KDE 4.4) | 315 | * @since 0.10 (KDE 4.4) | ||
225 | */ | 316 | */ | ||
226 | NormalizedPoint center() const; | 317 | NormalizedPoint center() const; | ||
227 | 318 | | |||
228 | /** | 319 | /** | ||
229 | * Transforms the normalized rectangle with the operations defined by @p matrix. | 320 | * Transforms the normalized rectangle with the operations defined by @p matrix. | ||
230 | */ | 321 | */ | ||
231 | void transform( const QTransform &matrix ); | 322 | void transform( const QTransform &matrix ); | ||
232 | 323 | | |||
233 | /** | 324 | /** | ||
234 | * Returns true if the point pt is located to the bottom of the rectangle | 325 | * Returns true if the point @p pt is located below the bottom of the rectangle | ||
235 | * @since 0.14 (KDE 4.8) | 326 | * @since 0.14 (KDE 4.8) | ||
236 | */ | 327 | */ | ||
237 | bool isBottom(const NormalizedPoint& pt) const | 328 | bool isBottom(const NormalizedPoint& pt) const | ||
238 | { | 329 | { | ||
239 | return bottom < pt.y; | 330 | return bottom < pt.y; | ||
240 | } | 331 | } | ||
241 | 332 | | |||
242 | /** | 333 | /** | ||
243 | * Returns true if the point pt is located on the top of the rectangle | 334 | * Returns true if the point @p pt is located above the top of the rectangle | ||
244 | * @since 0.14 (KDE 4.8) | 335 | * @since 0.14 (KDE 4.8) | ||
245 | */ | 336 | */ | ||
246 | bool isTop(const NormalizedPoint& pt) const | 337 | bool isTop(const NormalizedPoint& pt) const | ||
247 | { | 338 | { | ||
248 | return top > pt.y; | 339 | return top > pt.y; | ||
249 | } | 340 | } | ||
250 | 341 | | |||
251 | /** | 342 | /** | ||
252 | * Returns true if the point pt is located under the top of the rectangle | 343 | * Returns true if the point @p pt is located below the top of the rectangle | ||
253 | * @since 0.14 (KDE 4.8) | 344 | * @since 0.14 (KDE 4.8) | ||
254 | */ | 345 | */ | ||
255 | bool isBottomOrLevel(const NormalizedPoint& pt) const | 346 | bool isBottomOrLevel(const NormalizedPoint& pt) const | ||
256 | { | 347 | { | ||
257 | return top < pt.y; | 348 | return top < pt.y; | ||
258 | } | 349 | } | ||
259 | 350 | | |||
260 | /** | 351 | /** | ||
261 | * Returns true if the point pt is located above the bottom of the rectangle | 352 | * Returns true if the point @p pt is located above the bottom of the rectangle | ||
262 | * @since 0.14 (KDE 4.8) | 353 | * @since 0.14 (KDE 4.8) | ||
263 | */ | 354 | */ | ||
264 | bool isTopOrLevel(const NormalizedPoint& pt) const | 355 | bool isTopOrLevel(const NormalizedPoint& pt) const | ||
265 | { | 356 | { | ||
266 | return bottom > pt.y; | 357 | return bottom > pt.y; | ||
267 | } | 358 | } | ||
268 | 359 | | |||
269 | /** | 360 | /** | ||
270 | * Returns true if the point pt is located to the right of the left arm of rectangle | 361 | * Returns true if the point @p pt is located to the right of the left edge of the rectangle | ||
271 | * @since 0.14 (KDE 4.8) | 362 | * @since 0.14 (KDE 4.8) | ||
272 | */ | 363 | */ | ||
273 | bool isLeft(const NormalizedPoint& pt) const | 364 | bool isLeft(const NormalizedPoint& pt) const | ||
Adjectives like ‘left’ or ‘top’ aren’t very precise. Is the rectangle left of the point or is the point left of the rectangle? Additionally, this is inconsistent to ‘isTop’ <-> ‘isTopOrLevel’. I suggest to rename the functions to names like:
davidhurka: Adjectives like ‘left’ or ‘top’ aren’t very precise. Is the rectangle left of the point or is… | |||||
Breaking API is a big no no just because you don't like the name. The documentation clearly says what left means. aacid: Breaking API is a big no no just because you don't like the name.
The documentation clearly… | |||||
Didn’t realize OKULARCORE_EXPORT, bad idea to rename this. So I agree. This should also answer whether to replace scaleX and scaleY arguments by a struct. Wouldn’t have done that in this patch anyway. Bug 334297 is indirectly related, have to think about that. davidhurka: Didn’t realize OKULARCORE_EXPORT, bad idea to rename this. So I agree.
This should also answer… | |||||
274 | { | 365 | { | ||
275 | return left < pt.x; | 366 | return left < pt.x; | ||
276 | } | 367 | } | ||
277 | 368 | | |||
278 | /** | 369 | /** | ||
279 | * Returns true if the point pt is located to the left of the right arm of rectangle | 370 | * Returns true if the point @p pt is located to the left of the right edge of the rectangle | ||
280 | * @since 0.14 (KDE 4.8) | 371 | * @since 0.14 (KDE 4.8) | ||
281 | */ | 372 | */ | ||
282 | bool isRight(const NormalizedPoint& pt) const | 373 | bool isRight(const NormalizedPoint& pt) const | ||
283 | { | 374 | { | ||
284 | return right > pt.x; | 375 | return right > pt.x; | ||
285 | } | 376 | } | ||
286 | 377 | | |||
287 | /** | 378 | /** | ||
288 | * Returns the distance of the point @p x @p y @p xScale @p yScale to the closest | 379 | * Returns the squared distance of the normalized point (@p x, @p y) | ||
289 | * edge or 0 if the point is within the rectangle | 380 | * to the closest edge, or 0 if the point is within the rectangle; | ||
381 | * using a reference area of size @p xScale x @p yScale | ||||
290 | * @since 0.17 (KDE 4.11) | 382 | * @since 0.17 (KDE 4.11) | ||
291 | */ | 383 | */ | ||
292 | double distanceSqr(double x, double y, double xScale, double yScale) const | 384 | double distanceSqr(double x, double y, double xScale, double yScale) const | ||
293 | { | 385 | { | ||
294 | double distX = 0; | 386 | double distX = 0; | ||
295 | if ( x < left ) | 387 | if ( x < left ) | ||
296 | distX = left - x; | 388 | distX = left - x; | ||
297 | else if ( x > right ) | 389 | else if ( x > right ) | ||
Show All 37 Lines | |||||
335 | /** | 427 | /** | ||
336 | * The normalized bottom coordinate. | 428 | * The normalized bottom coordinate. | ||
337 | */ | 429 | */ | ||
338 | double bottom; | 430 | double bottom; | ||
339 | }; | 431 | }; | ||
340 | //KDE_DUMMY_QHASH_FUNCTION(NormalizedRect) | 432 | //KDE_DUMMY_QHASH_FUNCTION(NormalizedRect) | ||
341 | 433 | | |||
342 | /** | 434 | /** | ||
343 | * @short NormalizedRect that contains a reference to an object. | 435 | * @short An area with normalized coordinates that contains a reference to an object. | ||
“A reference to an ‘object’” is very broad. This is an area on a page (like RegularAreaRect), and links to an Annotation or SourceReference, or something “not owned”. Some bad alternative ideas to ‘ObjectRect’: ;)
davidhurka: “A reference to an ‘object’” is very broad.
This is an area on a page (like RegularAreaRect)… | |||||
aacid: We're not renaming ObjectRect. | |||||
344 | * | 436 | * | ||
345 | * These rects contains a pointer to a okular object (such as an action or something | 437 | * These areas ("rects") contain a pointer to a document object | ||
346 | * like that). The pointer is read and stored as 'void pointer' so cast is | 438 | * (such as a hyperlink, an action, or something like that). | ||
439 | * The pointer is read and stored as 'void pointer' so cast is | ||||
347 | * performed by accessors based on the value returned by objectType(). Objects | 440 | * performed by accessors based on the value returned by objectType(). Objects | ||
348 | * are reparented to this class. | 441 | * are reparented to this class. | ||
349 | * | 442 | * | ||
350 | * Type / Class correspondence tab: | 443 | * Type / Class correspondence tab: | ||
davidhurka: What does this mean? | |||||
No idea, you're the first peson ever that probably reads this line :D I used the power of git history and i think tab means table and the table tries to explain which kind of object the object() function returns. aacid: No idea, you're the first peson ever that probably reads this line :D
I used the power of git… | |||||
351 | * - Action : class Action: description of an action | 444 | * - Action : class Action: description of an action | ||
352 | * - Image : class Image : description of an image (n/a) | 445 | * - Image : class Image : description of an image (n/a) | ||
353 | * - Annotation: class Annotation: description of an annotation | 446 | * - Annotation: class Annotation: description of an annotation | ||
447 | * | ||||
448 | * For more information about the normalized coordinate system, see NormalizedPoint. | ||||
449 | * | ||||
450 | * @see NormalizedPoint | ||||
354 | */ | 451 | */ | ||
355 | class OKULARCORE_EXPORT ObjectRect | 452 | class OKULARCORE_EXPORT ObjectRect | ||
356 | { | 453 | { | ||
357 | public: | 454 | public: | ||
358 | /** | 455 | /** | ||
359 | * Describes the type of storable object. | 456 | * Describes the type of storable object. | ||
360 | */ | 457 | */ | ||
361 | enum ObjectType | 458 | enum ObjectType | ||
362 | { | 459 | { | ||
363 | Action, ///< An action | 460 | Action, ///< An action | ||
364 | Image, ///< An image | 461 | Image, ///< An image | ||
365 | OAnnotation, ///< An annotation | 462 | OAnnotation, ///< An annotation | ||
366 | SourceRef ///< A source reference | 463 | SourceRef ///< A source reference | ||
367 | }; | 464 | }; | ||
368 | 465 | | |||
369 | /** | 466 | /** | ||
370 | * Creates a new object rectangle. | 467 | * Creates a new object rectangle. | ||
371 | * | 468 | * | ||
372 | * @param left The left coordinate of the rectangle. | 469 | * @param left The left coordinate of the rectangle. | ||
373 | * @param top The top coordinate of the rectangle. | 470 | * @param top The top coordinate of the rectangle. | ||
374 | * @param right The right coordinate of the rectangle. | 471 | * @param right The right coordinate of the rectangle. | ||
375 | * @param bottom The bottom coordinate of the rectangle. | 472 | * @param bottom The bottom coordinate of the rectangle. | ||
376 | * @param ellipse If true the rectangle describes an ellipse. | 473 | * @param ellipse If true the rectangle describes an ellipse. | ||
What’s the purpose of ‘ellipse’? Currently it’s not used. Are any of these parameters used at all? davidhurka: What’s the purpose of ‘ellipse’? Currently it’s not used.
Are any of these parameters used at… | |||||
What do you mean ellipse is not used? It is used here, isn't it? aacid: What do you mean ellipse is not used?
It is used here, isn't it?
https://cgit.kde.org/okular. | |||||
I meant whether it is used by anything which calls ObjectRect. But everything seems to implement own stuff to populate the QPainterPath. davidhurka: I meant whether it is used by anything which calls ObjectRect. But everything seems to… | |||||
377 | * @param type The type of the storable object @see ObjectType. | 474 | * @param type The type of the storable object @see ObjectType. | ||
378 | * @param object The pointer to the storable object. | 475 | * @param object The pointer to the storable object. | ||
379 | */ | 476 | */ | ||
380 | ObjectRect( double left, double top, double right, double bottom, bool ellipse, ObjectType type, void *object ); | 477 | ObjectRect( double left, double top, double right, double bottom, bool ellipse, ObjectType type, void *object ); | ||
381 | 478 | | |||
382 | /** | 479 | /** | ||
383 | * This is an overloaded member function, provided for convenience. | 480 | * This is an overloaded member function, provided for convenience. | ||
384 | */ | 481 | */ | ||
Show All 27 Lines | |||||
412 | 509 | | |||
413 | /** | 510 | /** | ||
414 | * Returns the bounding rect of the object rectangle for the | 511 | * Returns the bounding rect of the object rectangle for the | ||
415 | * scaling factor @p xScale and @p yScale. | 512 | * scaling factor @p xScale and @p yScale. | ||
416 | */ | 513 | */ | ||
417 | virtual QRect boundingRect( double xScale, double yScale ) const; | 514 | virtual QRect boundingRect( double xScale, double yScale ) const; | ||
418 | 515 | | |||
419 | /** | 516 | /** | ||
420 | * Returns whether the object rectangle contains the point @p x, @p y for the | 517 | * Returns whether the object rectangle contains the point with absolute coordinates | ||
421 | * scaling factor @p xScale and @p yScale. | 518 | * (@p x, @p y) at a page size of @p xScale x @p yScale. | ||
The base class implementation just ignores the page size and takes the point as normalized. This method is not used anywhere. Maybe it should be fixed, ore be pure virtual? davidhurka: The base class implementation just ignores the page size and takes the point as normalized. | |||||
What do you mean it's not used anywhere? Have you tried marking it as pure virtual? aacid: What do you mean it's not used anywhere? Have you tried marking it as pure virtual? | |||||
pure virtual does not work becaues ObjectRect is instantiated. I still don’t find it used anywhere. davidhurka: pure virtual does not work becaues ObjectRect is instantiated.
I still don’t find it used… | |||||
422 | */ | 519 | */ | ||
423 | virtual bool contains( double x, double y, double xScale, double yScale ) const; | 520 | virtual bool contains( double x, double y, double xScale, double yScale ) const; | ||
424 | 521 | | |||
425 | /** | 522 | /** | ||
426 | * Transforms the object rectangle with the operations defined by @p matrix. | 523 | * Transforms the object rectangle with the operations defined by @p matrix. | ||
427 | */ | 524 | */ | ||
428 | virtual void transform( const QTransform &matrix ); | 525 | virtual void transform( const QTransform &matrix ); | ||
429 | 526 | | |||
430 | /** | 527 | /** | ||
431 | * Returns the square of the distance between the object and the point @p x, @p y | 528 | * Returns the squared distance between the object | ||
432 | * for the scaling factor @p xScale and @p yScale. | 529 | * and the point with | ||
530 | * normalized coordinates (@p x, @p y) | ||||
531 | * at a page size of @p xScale x @p yScale. | ||||
433 | * | 532 | * | ||
434 | * @since 0.8.2 (KDE 4.2.2) | 533 | * @since 0.8.2 (KDE 4.2.2) | ||
435 | */ | 534 | */ | ||
436 | // FIXME this should most probably be a virtual method | 535 | // FIXME this should most probably be a virtual method | ||
437 | double distanceSqr( double x, double y, double xScale, double yScale ) const; | 536 | double distanceSqr( double x, double y, double xScale, double yScale ) const; | ||
438 | 537 | | |||
439 | protected: | 538 | protected: | ||
440 | ObjectType m_objectType; | 539 | ObjectType m_objectType; | ||
▲ Show 20 Lines • Show All 101 Lines • ▼ Show 20 Line(s) | |||||
542 | template <typename T> | 641 | template <typename T> | ||
543 | T& deref( T& t ) | 642 | T& deref( T& t ) | ||
544 | { | 643 | { | ||
545 | return t; | 644 | return t; | ||
546 | } | 645 | } | ||
547 | /// @endcond | 646 | /// @endcond | ||
548 | 647 | | |||
549 | /** | 648 | /** | ||
550 | * @short A regular area of NormalizedShape which normalizes a Shape | 649 | * @short An area with normalized coordinates, consisting of NormalizedShape objects. | ||
650 | * | ||||
651 | * This is a template class to describe an area which consists of | ||||
652 | * multiple shapes of the same type, intersecting or non-intersecting. | ||||
653 | * The coordinates are normalized, and can be mapped to a reference area of defined size. | ||||
654 | * For more information about the normalized coordinate system, see NormalizedPoint. | ||||
551 | * | 655 | * | ||
552 | * Class NormalizedShape \b must have the following functions/operators defined: | 656 | * Class NormalizedShape \b must have the following functions/operators defined: | ||
553 | * - bool contains( double, double ) | 657 | * - bool contains( double, double ), whether it contains the given NormalizedPoint | ||
554 | * - bool intersects( NormalizedShape ) | 658 | * - bool intersects( NormalizedShape ) | ||
555 | * - bool isNull() | 659 | * - bool isNull() | ||
556 | * - Shape geometry( int, int ) | 660 | * - Shape geometry( int, int ), which maps to the reference area | ||
557 | * - operator|=( NormalizedShape ) which unite two NormalizedShape's | 661 | * - operator|=( NormalizedShape ), which unites two NormalizedShape's | ||
662 | * | ||||
663 | * @see RegularAreaRect, NormalizedPoint | ||||
558 | */ | 664 | */ | ||
559 | template <class NormalizedShape, class Shape> class RegularArea : public QList<NormalizedShape> | 665 | template <class NormalizedShape, class Shape> class RegularArea : public QList<NormalizedShape> | ||
560 | { | 666 | { | ||
561 | public: | 667 | public: | ||
562 | /** | 668 | /** | ||
563 | * Returns whether the regular area contains the | 669 | * Returns whether this area contains the normalized point (@p x, @p y). | ||
564 | * normalized point @p x, @p y. | | |||
565 | */ | 670 | */ | ||
566 | bool contains( double x, double y ) const; | 671 | bool contains( double x, double y ) const; | ||
567 | 672 | | |||
568 | /** | 673 | /** | ||
569 | * Returns whether the regular area contains the | 674 | * Returns whether this area contains a NormalizedShape object that equals @p shape. | ||
570 | * given @p shape. | | |||
571 | */ | 675 | */ | ||
572 | bool contains( const NormalizedShape& shape ) const; | 676 | bool contains( const NormalizedShape& shape ) const; | ||
573 | 677 | | |||
574 | /** | 678 | /** | ||
575 | * Returns whether the regular area intersects with the given @p area. | 679 | * Returns whether this area intersects with the given @p area. | ||
576 | */ | 680 | */ | ||
577 | bool intersects( const RegularArea<NormalizedShape,Shape> *area ) const; | 681 | bool intersects( const RegularArea<NormalizedShape,Shape> *area ) const; | ||
578 | 682 | | |||
579 | /** | 683 | /** | ||
580 | * Returns whether the regular area intersects with the given @p shape. | 684 | * Returns whether the regular area intersects with the given @p shape. | ||
581 | */ | 685 | */ | ||
582 | bool intersects( const NormalizedShape& shape ) const; | 686 | bool intersects( const NormalizedShape& shape ) const; | ||
583 | 687 | | |||
584 | /** | 688 | /** | ||
585 | * Appends the given @p area to the regular area. | 689 | * Appends the given @p area to this area. | ||
586 | */ | 690 | */ | ||
587 | void appendArea( const RegularArea<NormalizedShape,Shape> *area ); | 691 | void appendArea( const RegularArea<NormalizedShape,Shape> *area ); | ||
588 | 692 | | |||
589 | /** | 693 | /** | ||
590 | * Appends the given @p shape to the regular area. | 694 | * Appends the given @p shape to this area. | ||
591 | */ | 695 | */ | ||
592 | void appendShape( const NormalizedShape& shape, MergeSide side = MergeAll ); | 696 | void appendShape( const NormalizedShape& shape, MergeSide side = MergeAll ); | ||
593 | 697 | | |||
594 | /** | 698 | /** | ||
595 | * Simplifies the regular area by merging its intersecting subareas. | 699 | * Simplifies this regular area by merging its intersecting subareas. | ||
700 | * This might change the effective geometry of this area. | ||||
596 | */ | 701 | */ | ||
597 | void simplify(); | 702 | void simplify(); | ||
598 | 703 | | |||
599 | /** | 704 | /** | ||
600 | * Returns whether the regular area is a null area. | 705 | * Returns whether the regular area is a null area. | ||
601 | */ | 706 | */ | ||
602 | bool isNull() const; | 707 | bool isNull() const; | ||
603 | 708 | | |||
604 | /** | 709 | /** | ||
605 | * Returns the subareas of the regular areas as shapes for the given scaling factor | 710 | * Returns the subareas of this regular area | ||
606 | * @p xScale and @p yScale, translated by @p dx and @p dy. | 711 | * mapped to a reference area of size @p xScale x @p yScale, | ||
712 | * then translated by @p dx and @p dy. | ||||
607 | */ | 713 | */ | ||
608 | QList<Shape> geometry( int xScale, int yScale, int dx = 0, int dy = 0 ) const; | 714 | QList<Shape> geometry( int xScale, int yScale, int dx = 0, int dy = 0 ) const; | ||
609 | 715 | | |||
610 | /** | 716 | /** | ||
611 | * Transforms the regular area with the operations defined by @p matrix. | 717 | * Transforms the regular area with the operations defined by @p matrix. | ||
612 | */ | 718 | */ | ||
613 | void transform( const QTransform &matrix ); | 719 | void transform( const QTransform &matrix ); | ||
614 | }; | 720 | }; | ||
▲ Show 20 Lines • Show All 199 Lines • ▼ Show 20 Line(s) | |||||
814 | { | 920 | { | ||
815 | if ( this->isEmpty() ) | 921 | if ( this->isEmpty() ) | ||
816 | return; | 922 | return; | ||
817 | 923 | | |||
818 | for ( int i = 0; i < this->count(); ++i ) | 924 | for ( int i = 0; i < this->count(); ++i ) | ||
819 | givePtr( (*this)[i] )->transform( matrix ); | 925 | givePtr( (*this)[i] )->transform( matrix ); | ||
820 | } | 926 | } | ||
821 | 927 | | |||
928 | /** | ||||
929 | * This is a list of NormalizedRect, to describe an area consisting of | ||||
930 | * multiple rectangles using normalized coordinates. | ||||
931 | * | ||||
932 | * This area can be mapped to a reference area, resulting in a list of QRects. | ||||
933 | * For more information about the normalized coordinate system, see NormalizedPoint. | ||||
934 | * | ||||
This comment is weird, it seems to imply such functionality exists in this class, when it doesn't. aacid: This comment is weird, it seems to imply such functionality exists in this class, when it… | |||||
davidhurka: Doesn’t RegularAreaRect::geometry() do that? | |||||
935 | * Okular uses this area e. g. to describe a text highlight area, | ||||
936 | * which consists of multiple, intersecting or non-intersecting rectangles. | ||||
937 | * | ||||
938 | * @see NormalizedRect, NormalizedPoint | ||||
939 | */ | ||||
822 | class OKULARCORE_EXPORT RegularAreaRect : public RegularArea< NormalizedRect, QRect > | 940 | class OKULARCORE_EXPORT RegularAreaRect : public RegularArea< NormalizedRect, QRect > | ||
823 | { | 941 | { | ||
824 | public: | 942 | public: | ||
825 | RegularAreaRect(); | 943 | RegularAreaRect(); | ||
826 | RegularAreaRect( const RegularAreaRect& rar ); | 944 | RegularAreaRect( const RegularAreaRect& rar ); | ||
827 | ~RegularAreaRect(); | 945 | ~RegularAreaRect(); | ||
828 | 946 | | |||
829 | RegularAreaRect& operator=( const RegularAreaRect& rar ); | 947 | RegularAreaRect& operator=( const RegularAreaRect& rar ); | ||
830 | 948 | | |||
831 | private: | 949 | private: | ||
832 | class Private; | 950 | class Private; | ||
833 | Private * const d; | 951 | Private * const d; | ||
834 | }; | 952 | }; | ||
835 | 953 | | |||
836 | /** | 954 | /** | ||
837 | * This class stores the coordinates of a highlighting area | 955 | * This class stores the geometry of a highlighting area in normalized coordinates, | ||
838 | * together with the id of the highlight owner and the color. | 956 | * together with highlighting specific information. | ||
839 | */ | 957 | */ | ||
840 | class HighlightAreaRect : public RegularAreaRect | 958 | class HighlightAreaRect : public RegularAreaRect | ||
841 | { | 959 | { | ||
842 | public: | 960 | public: | ||
843 | /** | 961 | /** | ||
844 | * Creates a new highlight area rect with the coordinates of | 962 | * Creates a new highlight area rect with the coordinates of | ||
845 | * the given @p area. | 963 | * the given @p area. | ||
846 | */ | 964 | */ | ||
Show All 30 Lines |
i don't see why your version of the text is better.