/
qgscomposeritem.sip
583 lines (492 loc) · 21.7 KB
/
qgscomposeritem.sip
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
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
/** \ingroup MapComposer
* A item that forms part of a map composition.
*/
class QgsComposerItem : QObject, QGraphicsRectItem
{
%TypeHeaderCode
#include <qgscomposeritem.h>
#include <qgscomposerlabel.h>
#include <qgscomposerlegend.h>
#include <qgscomposermap.h>
#include <qgspaperitem.h>
#include <qgscomposerpicture.h>
#include <qgscomposerscalebar.h>
#include <qgscomposershape.h>
#include <qgscomposertable.h>
#include <qgscomposerattributetable.h>
%End
%ConvertToSubClassCode
// the conversions have to be static, because they're using multiple inheritance
// (seen in PyQt4 .sip files for some QGraphicsItem classes)
switch (sipCpp->type())
{
case QgsComposerItem::ComposerItem:
sipClass = sipClass_QgsComposerItem;
*sipCppRet = static_cast<QgsComposerItem*>(sipCpp);
break;
#if 0
case QgsComposerItem::ComposerArrow:
sipClass = sipClass_QgsComposerArrow;
*sipCppRet = static_cast<QgsComposerArrow*>(sipCpp);
break;
case QgsComposerItem::ComposerItemGroup:
sipClass = sipClass_QgsComposerItemGroup;
*sipCppRet = static_cast<QgsComposerItemGroup*>(sipCpp);
break;
#endif
case QgsComposerItem::ComposerLabel:
sipClass = sipClass_QgsComposerLabel;
*sipCppRet = static_cast<QgsComposerLabel*>(sipCpp);
break;
case QgsComposerItem::ComposerLegend:
sipClass = sipClass_QgsComposerLegend;
*sipCppRet = static_cast<QgsComposerLegend*>(sipCpp);
break;
case QgsComposerItem::ComposerMap:
sipClass = sipClass_QgsComposerMap;
*sipCppRet = static_cast<QgsComposerMap*>(sipCpp);
break;
case QgsComposerItem::ComposerPaper:
sipClass = sipClass_QgsPaperItem;
*sipCppRet = static_cast<QgsPaperItem*>(sipCpp);
break;
case QgsComposerItem::ComposerPicture:
sipClass = sipClass_QgsComposerPicture;
*sipCppRet = static_cast<QgsComposerPicture*>(sipCpp);
break;
case QgsComposerItem::ComposerScaleBar:
sipClass = sipClass_QgsComposerScaleBar;
*sipCppRet = static_cast<QgsComposerScaleBar*>(sipCpp);
break;
case QgsComposerItem::ComposerShape:
sipClass = sipClass_QgsComposerShape;
*sipCppRet = static_cast<QgsComposerShape*>(sipCpp);
break;
case QgsComposerItem::ComposerTable:
sipClass = sipClass_QgsComposerTable;
*sipCppRet = static_cast<QgsComposerTable*>(sipCpp);
break;
case QgsComposerItem::ComposerAttributeTable:
sipClass = sipClass_QgsComposerAttributeTable;
*sipCppRet = static_cast<QgsComposerAttributeTable*>(sipCpp);
break;
/*
case QgsComposerItem::ComposerTextTable:
sipClass = sipClass_QgsComposerTextTable;
*sipCppRet = static_cast<QgsComposerTextTable*>(sipCpp);
break;
*/
default:
sipClass = 0;
}
%End
public:
enum ItemType
{
// base class for the items
ComposerItem,
// derived classes
ComposerArrow,
ComposerItemGroup,
ComposerLabel,
ComposerLegend,
ComposerMap,
ComposerPaper, // QgsPaperItem
ComposerPicture,
ComposerScaleBar,
ComposerShape,
ComposerTable,
ComposerAttributeTable,
ComposerTextTable,
ComposerFrame
};
/**Describes the action (move or resize in different directon) to be done during mouse move*/
enum MouseMoveAction
{
MoveItem,
ResizeUp,
ResizeDown,
ResizeLeft,
ResizeRight,
ResizeLeftUp,
ResizeRightUp,
ResizeLeftDown,
ResizeRightDown,
NoAction
};
enum ItemPositionMode
{
UpperLeft,
UpperMiddle,
UpperRight,
MiddleLeft,
Middle,
MiddleRight,
LowerLeft,
LowerMiddle,
LowerRight
};
/**Constructor
@param composition parent composition
@param manageZValue true if the z-Value of this object should be managed by mComposition*/
QgsComposerItem( QgsComposition* composition /TransferThis/, bool manageZValue = true );
/**Constructor with box position and composer object
@param x x coordinate of item
@param y y coordinate of item
@param width width of item
@param height height of item
@param composition parent composition
@param manageZValue true if the z-Value of this object should be managed by mComposition*/
QgsComposerItem( qreal x, qreal y, qreal width, qreal height, QgsComposition* composition /TransferThis/, bool manageZValue = true );
virtual ~QgsComposerItem();
/** return correct graphics item type. Added in v1.7 */
virtual int type() const;
/** \brief Set selected, selected item should be highlighted */
virtual void setSelected( bool s );
/** \brief Is selected */
virtual bool selected() const;
/** stores state in project */
virtual bool writeSettings();
/** read state from project */
virtual bool readSettings();
/** delete settings from project file */
virtual bool removeSettings();
/**Moves item in canvas coordinates*/
void move( double dx, double dy );
/**Move Content of item. Does nothing per default (but implemented in composer map)
@param dx move in x-direction (canvas coordinates)
@param dy move in y-direction(canvas coordinates)*/
virtual void moveContent( double dx, double dy );
/**Zoom content of item. Does nothing per default (but implemented in composer map)
@param delta value from wheel event that describes magnitude and direction (positive /negative number)
@param x x-position of mouse cursor (in item coordinates)
@param y y-position of mouse cursor (in item coordinates)*/
virtual void zoomContent( int delta, double x, double y );
/**Gets the page the item is currently on.
* @returns page number for item
* @see pagePos
* @see updatePagePos
* @note this method was added in version 2.4
*/
int page() const;
/**Returns the item's position relative to its current page.
* @returns position relative to the page's top left corner.
* @see page
* @see updatePagePos
* @note this method was added in version 2.4
*/
QPointF pagePos() const;
/**Moves the item so that it retains its relative position on the page
* when the paper size changes.
* @param newPageWidth new width of the page in mm
* @param newPageHeight new height of the page in mm
* @see page
* @see pagePos
* @note this method was added in version 2.4
*/
void updatePagePos( double newPageWidth, double newPageHeight );
/**Moves the item to a new position (in canvas coordinates)*/
void setItemPosition( double x, double y, ItemPositionMode itemPoint = UpperLeft );
/**Sets item position and width / height in one go
@param x item position x
@param y item position y
@param width item width
@param height item height
@param itemPoint item position mode
@param posIncludesFrame set to true if the position and size arguments include the item's frame border
@note: this method was added in version 1.6*/
void setItemPosition( double x, double y, double width, double height, ItemPositionMode itemPoint = UpperLeft, bool posIncludesFrame = false );
/**Returns item's last used position mode.
@note: This property has no effect on actual's item position, which is always the top-left corner.
@note: this method was added in version 2.0*/
ItemPositionMode lastUsedPositionMode();
/**Sets this items bound in scene coordinates such that 1 item size units
corresponds to 1 scene size unit*/
virtual void setSceneRect( const QRectF& rectangle );
/** stores state in Dom element
* @param elem is Dom element corresponding to 'Composer' tag
* @param doc is the Dom document
*/
virtual bool writeXML( QDomElement& elem, QDomDocument & doc ) const = 0;
/**Writes parameter that are not subclass specific in document. Usually called from writeXML methods of subclasses*/
bool _writeXML( QDomElement& itemElem, QDomDocument& doc ) const;
/** sets state from Dom document
* @param itemElem is Dom node corresponding to item tag
* @param doc is Dom document
*/
virtual bool readXML( const QDomElement& itemElem, const QDomDocument& doc ) = 0;
/**Reads parameter that are not subclass specific in document. Usually called from readXML methods of subclasses*/
bool _readXML( const QDomElement& itemElem, const QDomDocument& doc );
/** Whether this item has a frame or not.
* @returns true if there is a frame around this item, otherwise false.
* @note introduced since 1.8
* @see hasFrame
*/
bool hasFrame() const;
/** Set whether this item has a frame drawn around it or not.
* @param drawFrame draw frame
* @returns nothing
* @note introduced in 1.8
* @see hasFrame
*/
void setFrameEnabled( bool drawFrame );
/** Sets frame outline width
* @param outlineWidth new width for outline frame
* @returns nothing
* @note introduced in 2.2
* @see setFrameEnabled
*/
virtual void setFrameOutlineWidth( double outlineWidth );
/** Returns the frame's outline width. Only used if hasFrame is true.
* @returns Frame outline width
* @note introduced in 2.3
* @see hasFrame
* @see setFrameOutlineWidth
*/
double frameOutlineWidth() const;
/** Returns the join style used for drawing the item's frame
* @returns Join style for outline frame
* @note introduced in 2.3
* @see hasFrame
* @see setFrameJoinStyle
*/
Qt::PenJoinStyle frameJoinStyle() const;
/** Sets join style used when drawing the item's frame
* @param style Join style for outline frame
* @returns nothing
* @note introduced in 2.3
* @see setFrameEnabled
* @see frameJoinStyle
*/
void setFrameJoinStyle( Qt::PenJoinStyle style );
/** Returns the estimated amount the item's frame bleeds outside the item's
* actual rectangle. For instance, if the item has a 2mm frame outline, then
* 1mm of this frame is drawn outside the item's rect. In this case the
* return value will be 1.0
* @note introduced in 2.2
*/
virtual double estimatedFrameBleed() const;
/** Returns the item's rectangular bounds, including any bleed caused by the item's frame.
* The bounds are returned in the item's coordinate system (see Qt's QGraphicsItem docs for
* more details about QGraphicsItem coordinate systems). The results differ from Qt's rect()
* function, as rect() makes no allowances for the portion of outlines which are drawn
* outside of the item.
* @note introduced in 2.2
* @see estimatedFrameBleed
*/
virtual QRectF rectWithFrame() const;
/** Whether this item has a Background or not.
* @returns true if there is a Background around this item, otherwise false.
* @note introduced since 2.0
* @see hasBackground
*/
bool hasBackground() const;
/** Set whether this item has a Background drawn around it or not.
* @param drawBackground draw Background
* @returns nothing
* @note introduced in 2.0
* @see hasBackground
*/
void setBackgroundEnabled( bool drawBackground );
/** Gets the background color for this item
* @returns background color
* @note introduced in 2.0
*/
QColor backgroundColor() const;
/** Sets the background color for this item
* @param backgroundColor new background color
* @returns nothing
* @note introduced in 2.0
*/
void setBackgroundColor( const QColor& backgroundColor );
/** Returns the item's composition blending mode */
QPainter::CompositionMode blendMode() const;
/** Sets the item's composition blending mode*/
void setBlendMode( QPainter::CompositionMode blendMode );
/** Returns the item's transparency */
int transparency() const;
/** Sets the item's transparency */
void setTransparency( int transparency );
/** Returns true if effects (eg blend modes) are enabled for the item
* @note introduced in 2.0
*/
bool effectsEnabled() const;
/** Sets whether effects (eg blend modes) are enabled for the item
* @note introduced in 2.0
*/
void setEffectsEnabled( bool effectsEnabled );
/**Composite operations for item groups do nothing per default*/
virtual void addItem( QgsComposerItem* item );
virtual void removeItems();
const QgsComposition* composition() const;
virtual void beginItemCommand( const QString& text );
/**Starts new composer undo command
@param commandText command title
@param c context for mergeable commands (unknown for non-mergeable commands*/
void beginCommand( const QString& commandText, QgsComposerMergeCommand::Context c = QgsComposerMergeCommand::Unknown );
virtual void endItemCommand();
/**Finish current command and push it onto the undo stack */
void endCommand();
void cancelCommand();
//functions that encapsulate the workaround for the Qt font bug (that is to scale the font size up and then scale the
//painter down by the same factor for drawing
/**Draws Text. Takes care about all the composer specific issues (calculation to pixel, scaling of font and painter
to work around the Qt font bug)*/
void drawText( QPainter* p, double x, double y, const QString& text, const QFont& font ) const;
/**Like the above, but with a rectangle for multiline text
* @param p painter to use
* @param rect rectangle to draw into
* @param text text to draw
* @param font font to use
* @param halignment optional horizontal alignment
* @param valignment optional vertical alignment
* @param flags allows for passing Qt::TextFlags to control appearance of rendered text
*/
void drawText( QPainter* p, const QRectF& rect, const QString& text, const QFont& font, Qt::AlignmentFlag halignment = Qt::AlignLeft, Qt::AlignmentFlag valignment = Qt::AlignTop, int flags = Qt::TextWordWrap ) const;
/**Returns the font width in millimeters (considers upscaling and downscaling with FONT_WORKAROUND_SCALE*/
double textWidthMillimeters( const QFont& font, const QString& text ) const;
/**Returns the font height of a character in millimeters
@note this method was added in version 1.7*/
double fontHeightCharacterMM( const QFont& font, const QChar& c ) const;
/**Returns the font ascent in Millimeters (considers upscaling and downscaling with FONT_WORKAROUND_SCALE*/
double fontAscentMillimeters( const QFont& font ) const;
/**Returns the font descent in Millimeters (considers upscaling and downscaling with FONT_WORKAROUND_SCALE*/
double fontDescentMillimeters( const QFont& font ) const;
/**Returns the font height in Millimeters (considers upscaling and downscaling with FONT_WORKAROUND_SCALE.
* Font height equals the font ascent+descent+1 (for baseline).
* @note Added in version 2.4
*/
double fontHeightMillimeters( const QFont& font ) const;
/**Calculates font to from point size to pixel size*/
double pixelFontSize( double pointSize ) const;
/**Returns a font where size is in pixel and font size is upscaled with FONT_WORKAROUND_SCALE*/
QFont scaledFontPixelSize( const QFont& font ) const;
/**Locks / unlocks the item position for mouse drags
@note this method was added in version 1.2*/
void setPositionLock( bool lock );
/**Returns position lock for mouse drags (true means locked)
@note this method was added in version 1.2*/
bool positionLock() const;
/**Returns the rotation for the composer item
@note this method was added in version 2.1*/
double itemRotation() const;
/**Returns the rotation for the composer item
* @deprecated Use itemRotation()
* instead
*/
double rotation() const /Deprecated/;
/**Updates item, with the possibility to do custom update for subclasses*/
virtual void updateItem();
/**Get item's id (which is not necessarly unique)
@note this method was added in version 1.7*/
QString id() const;
/**Set item's id (which is not necessarly unique)
@note this method was added in version 1.7*/
void setId( const QString& id );
/**Get item identification name
@note this method was added in version 2.0
@note there is not setter since one can't manually set the id*/
QString uuid() const;
/**Get the number of layers that this item requires for exporting as layers
* @returns 0 if this item is to be placed on the same layer as the previous item,
* 1 if it should be placed on its own layer, and >1 if it requires multiple export layers
* @note this method was added in version 2.4
*/
int numberExportLayers() const;
/**Sets the current layer to draw for exporting
* @param layerIdx can be set to -1 to draw all item layers, and must be less than numberExportLayers()
* @note this method was added in version 2.4
*/
void setCurrentExportLayer( int layerIdx = -1 );
public slots:
/**Sets the item rotation
* @deprecated Use setItemRotation( double rotation ) instead
*/
virtual void setRotation( double r );
/**Sets the item rotation
@param r item rotation in degrees
@param adjustPosition set to true if item should be shifted so that rotation occurs
around item center. If false, rotation occurs around item origin
@note this method was added in version 2.1
*/
virtual void setItemRotation( double r, bool adjustPosition = false );
void repaint();
protected:
//event handlers
virtual void mouseMoveEvent( QGraphicsSceneMouseEvent * event );
virtual void mousePressEvent( QGraphicsSceneMouseEvent * event );
virtual void mouseReleaseEvent( QGraphicsSceneMouseEvent * event );
virtual void hoverMoveEvent( QGraphicsSceneHoverEvent * event );
/**Draw selection boxes around item*/
virtual void drawSelectionBoxes( QPainter* p );
/**Draw black frame around item*/
virtual void drawFrame( QPainter* p );
/**Draw background*/
virtual void drawBackground( QPainter* p );
/**Draws arrowhead*/
void drawArrowHead( QPainter* p, double x, double y, double angle, double arrowHeadWidth ) const;
/**Returns angle of the line from p1 to p2 (clockwise, starting at N)*/
double angle( const QPointF& p1, const QPointF& p2 ) const;
/**Returns the current (zoom level dependent) tolerance to decide if mouse position is close enough to the
item border for resizing*/
double rectHandlerBorderTolerance() const;
/**Returns the size of the lock symbol depending on the composer zoom level and the item size
@note: this function was introduced in version 1.2*/
double lockSymbolSize() const;
/**Returns the zoom factor of the graphics view.
@return the factor or -1 in case of error (e.g. graphic view does not exist)
@note: this function was introduced in version 1.2*/
double horizontalViewScaleFactor() const;
//some utility functions
/**Calculates width and hight of the picture (in mm) such that it fits into the item frame with the given rotation*/
bool imageSizeConsideringRotation( double& width, double& height, double rotation ) const;
/**Calculates width and hight of the picture (in mm) such that it fits into the item frame with the given rotation
* @deprecated Use bool imageSizeConsideringRotation( double& width, double& height, double rotation )
* instead
*/
bool imageSizeConsideringRotation( double& width, double& height ) const /Deprecated/;
/**Calculates the largest scaled version of originalRect which fits within boundsRect, when it is rotated by
* a specified amount
@param originalRect QRectF to be rotated and scaled
@param boundsRect QRectF specifying the bounds which the rotated and scaled rectangle must fit within
@param rotation the rotation in degrees to be applied to the rectangle
*/
QRectF largestRotatedRectWithinBounds( QRectF originalRect, QRectF boundsRect, double rotation ) const;
/**Calculates corner point after rotation and scaling*/
bool cornerPointOnRotatedAndScaledRect( double& x, double& y, double width, double height, double rotation ) const;
/**Calculates corner point after rotation and scaling
* @deprecated Use bool cornerPointOnRotatedAndScaledRect( double& x, double& y, double width, double height, double rotation )
* instead
*/
bool cornerPointOnRotatedAndScaledRect( double& x, double& y, double width, double height ) const /Deprecated/;
/**Calculates width / height of the bounding box of a rotated rectangle*/
void sizeChangedByRotation( double& width, double& height, double rotation );
/**Calculates width / height of the bounding box of a rotated rectangle
* @deprecated Use void sizeChangedByRotation( double& width, double& height, double rotation )
* instead
*/
void sizeChangedByRotation( double& width, double& height ) /Deprecated/;
/**Rotates a point / vector
@param angle rotation angle in degrees, counterclockwise
@param x in/out: x coordinate before / after the rotation
@param y in/out: y cooreinate before / after the rotation*/
void rotate( double angle, double& x, double& y ) const;
/**Return horizontal align snap item. Creates a new graphics line if 0*/
QGraphicsLineItem* hAlignSnapItem();
void deleteHAlignSnapItem();
/**Return vertical align snap item. Creates a new graphics line if 0*/
QGraphicsLineItem* vAlignSnapItem();
void deleteVAlignSnapItem();
void deleteAlignItems();
signals:
/**Is emitted on item rotation change*/
void itemRotationChanged( double newRotation );
/**Used e.g. by the item widgets to update the gui elements*/
void itemChanged();
/**Emitted if the rectangle changes*/
void sizeChanged();
/**Emitted if the item's frame style changes
* @note: this function was introduced in version 2.2
*/
void frameChanged();
};