Members of the KDE Community are recommended to subscribe to the kde-community mailing list at https://mail.kde.org/mailman/listinfo/kde-community to allow them to participate in important discussions and receive other important announcements

KoShape.h 43.1 KB
Newer Older
Thomas Zander's avatar
Thomas Zander committed
1
/* This file is part of the KDE project
2
   Copyright (C) 2006-2008 Thorsten Zachmann <zachmann@kde.org>
3
   Copyright (C) 2006, 2008 Casper Boemann <cbr@boemann.dk>
4
   Copyright (C) 2006-2010 Thomas Zander <zander@kde.org>
5
   Copyright (C) 2007-2009,2011 Jan Hambrecht <jaham@gmx.net>
Thomas Zander's avatar
Thomas Zander committed
6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22

   This library is free software; you can redistribute it and/or
   modify it under the terms of the GNU Library General Public
   License as published by the Free Software Foundation; either
   version 2 of the License, or (at your option) any later version.

   This library is distributed in the hope that it will be useful,
   but WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
   Library General Public License for more details.

   You should have received a copy of the GNU Library General Public License
   along with this library; see the file COPYING.LIB.  If not, write to
   the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
 * Boston, MA 02110-1301, USA.
*/

Thomas Zander's avatar
Thomas Zander committed
23 24
#ifndef KOSHAPE_H
#define KOSHAPE_H
Thomas Zander's avatar
Thomas Zander committed
25

26
#include "KoInsets.h"
27
#include "KoFlake.h"
28
#include "KoConnectionPoint.h"
29

30
#include <QTransform>
Thomas Zander's avatar
Thomas Zander committed
31
#include <QVector>
32
#include <QSet>
33
#include <QMap>
Thomas Zander's avatar
Thomas Zander committed
34
#include <QBrush>
35
#include <QMetaType>
Thomas Zander's avatar
Thomas Zander committed
36

37
#include <KoXmlReaderForward.h>
38

39
//#include <KoSnapData.h>
40

41 42
#include "flake_export.h"

Thomas Zander's avatar
Thomas Zander committed
43 44 45 46 47
class QPainter;
class QRectF;
class QPainterPath;

class KoShapeContainer;
48
class KoShapeStrokeModel;
49
class KoShapeBackground;
50
class KoShapeManager;
51
class KoShapeUserData;
52
class KoViewConverter;
53
class KoShapeApplicationData;
54
class KoShapeSavingContext;
55
class KoCanvasBase;
56
class KoShapeLoadingContext;
57
class KoGenStyle;
58
class KoShapeBasedDocumentBase;
59
class KoDataCenterBase;
60
class KoShapeShadow;
61
class KoEventAction;
62
class KoShapePrivate;
63
class KoFilterEffectStack;
64
class KoSnapData;
65
class KoClipPath;
66
class KoShapePaintingContext;
Thomas Zander's avatar
Thomas Zander committed
67 68

/**
69
 *
70
 * Base class for all flake shapes. Shapes extend this class
Thomas Zander's avatar
Thomas Zander committed
71 72 73
 * to allow themselves to be manipulated. This class just represents
 * a graphical shape in the document and can be manipulated by some default
 * tools in this library.
74
 *
75
 * Due to the limited responsibility of this class, the extending object
Thomas Zander's avatar
Thomas Zander committed
76
 * can have any data backend and is responsible for painting itself.
77
 *
78
 * We strongly suggest that any extending class will use a Model View
Thomas Zander's avatar
Thomas Zander committed
79
 * Controller (MVC) design where the View part is all in this class, as well
80
 * as the one that inherits from this one.  This allows the data that rests
Thomas Zander's avatar
Thomas Zander committed
81
 * in the model to be reused in different parts of the document. For example
82
 * by having two flake objects that show that same data. Or each showing a section of it.
83
 *
84 85 86 87 88
 * The KoShape data is completely in postscript-points (pt) (see KoUnit
 * for conversion methods to and from points).
 * This image will explain the real-world use of the shape and its options.
 * <img src="../flake_shape_coords.png" align=center><br>
 *  The Rotation center can be returned with absolutePosition()
89
 *
90
 * <p>Flake objects can be created in three ways:
91 92 93 94 95
 * <ul>
 *   <li>a simple new KoDerivedFlake(),
 *   <li>through an associated tool,
 *   <li>through a factory
 * </ul>
96
 *
Thomas Zander's avatar
Thomas Zander committed
97 98 99 100 101 102 103 104 105 106 107 108 109
 * <h1>Shape interaction notifications</h1>
 * We had several notification methods that allow your shape to be notified of changes in other
 * shapes positions or rotation etc.
 * <ol><li>The most general is KoShape::shapeChanged().<br>
 * a virtual method that you can use to check various changed to your shape made by tools or otherwise.</li>
 * <li>for shape hierarchies the parent may receive a notification when a child was modified.
 *  This is done though KoShapeContainerModel::childChanged()</li>
 * <li>any shape that is at a similar position as another shape there is collision detection.
 * You can register your shape to be sensitive to any changes like moving or whatever to
 * <b>other</b> shapes that intersect yours.
 * Such changes will then be notified to your shape using the method from (1) You should call
 * KoShape::setCollisionDetection(bool) to enable this.
 * </ol>
Thomas Zander's avatar
Thomas Zander committed
110
 */
111
class FLAKE_EXPORT KoShape
Thomas Zander's avatar
Thomas Zander committed
112 113
{
public:
114 115 116
    /// Used by shapeChanged() to select which change was made
    enum ChangeType {
        PositionChanged, ///< used after a setPosition()
117
        RotationChanged, ///< used after a setRotation()
Thomas Zander's avatar
Thomas Zander committed
118
        ScaleChanged,   ///< used after a scale()
Thomas Zander's avatar
Thomas Zander committed
119
        ShearChanged,   ///< used after a shear()
120
        SizeChanged,    ///< used after a setSize()
121
        GenericMatrixChange,    ///< used after the matrix was changed without knowing which property explicitly changed
122
        ParentChanged,   ///< used after a setParent()
123
        CollisionDetected, ///< used when another shape moved in our boundingrect
124
        Deleted, ///< the shape was deleted
125
        StrokeChanged, ///< the shapes stroke has changed
126
        BackgroundChanged, ///< the shapes background has changed
127
        ShadowChanged, ///< the shapes shadow has changed
128 129
        ParameterChanged, ///< the shapes parameter has changed (KoParameterShape only)
        ContentChanged, ///< the content of the shape changed e.g. a new image inside a pixmap/text change inside a textshape
130
        TextRunAroundChanged, ///< used after a setTextRunAroundSide()
Jan Hambrecht's avatar
Jan Hambrecht committed
131
        ChildChanged, ///< a child of a container was changed/removed. This is propagated to all parents
132 133
        ConnectionPointChanged, ///< a connection point has changed
        ClipPathChanged ///< the shapes clip path has changed
134 135
    };

136 137 138 139 140
    /// The behavior text should do when intersecting this shape.
    enum TextRunAroundSide {
        BiggestRunAroundSide,   ///< Run other text around the side that has the most space
        LeftRunAroundSide,      ///< Run other text around the left side of the frame
        RightRunAroundSide,     ///< Run other text around the right side of the frame
141
        EnoughRunAroundSide,      ///< Run other text dynamically around both sides of the shape, provided there is sufficient space left
142 143 144 145 146
        BothRunAroundSide,      ///< Run other text around both sides of the shape
        NoRunAround,            ///< The text will be completely avoiding the frame by keeping the horizontal space that this frame occupies blank.
        RunThrough              ///< The text will completely ignore the frame and layout as if it was not there
    };

147 148 149 150 151 152 153
    /// The behavior text should do when intersecting this shape.
    enum TextRunAroundContour {
        ContourBox,     /// Run other text around a bounding rect of the outline
        ContourFull,   ///< Run other text around also on the inside
        ContourOutside   ///< Run other text around only on the outside
    };

154 155 156
    /**
     * TODO
     */
157
    enum RunThroughLevel {
158 159 160 161
        Background,
        Foreground
    };

Thomas Zander's avatar
Thomas Zander committed
162 163 164 165 166 167 168 169 170 171 172 173 174 175
    /**
     * @brief Constructor
     */
    KoShape();

    /**
     * @brief Destructor
     */
    virtual ~KoShape();

    /**
     * @brief Paint the shape
     * The class extending this one is responsible for painting itself.  Since we do not
     * assume the shape is square the paint must also clear its background if it will draw
176
     * something transparent on top.
Thomas Zander's avatar
Thomas Zander committed
177 178 179 180
     * This can be done with a method like:
     * <code>
       painter.fillRect(converter.normalToView(QRectF(QPointF(0.0,0.0), size())), background());</code>
     * Or equavalent for non-square objects.
181 182
     * Do note that a shape's top-left is always at coordinate 0,0. Even if the shape itself is rotated
     * or translated.
Thomas Zander's avatar
Thomas Zander committed
183 184 185
     * @param painter used for painting the shape
     * @param converter to convert between internal and view coordinates.
     * @see applyConversion()
186
     * @param paintcontext the painting context.
Thomas Zander's avatar
Thomas Zander committed
187
     */
188
    virtual void paint(QPainter &painter, const KoViewConverter &converter, KoShapePaintingContext &paintcontext) = 0;
Thomas Zander's avatar
Thomas Zander committed
189

190 191 192 193 194 195
    /**
     * Load a shape from odf
     *
     * @param context the KoShapeLoadingContext used for loading
     * @param element element which represents the shape in odf
     *
196
     * @return false if loading failed
197
     */
198
    virtual bool loadOdf(const KoXmlElement &element, KoShapeLoadingContext &context) = 0;
199

200
    /**
201
     * @brief store the shape data as ODF XML.
Thomas Zander's avatar
fix dox  
Thomas Zander committed
202
     * This is the method that will be called when saving a shape as a described in
203
     * OpenDocument 9.2 Drawing Shapes.
Thorsten Zachmann's avatar
Thorsten Zachmann committed
204
     * @see saveOdfAttributes
205
     */
206
    virtual void saveOdf(KoShapeSavingContext &context) const = 0;
207 208

    /**
209 210 211 212 213 214
     * This method can be used while saving the shape as ODF to add the data
     * stored on this shape to the current element.
     *
     * @param context the context for the current save.
     * @param attributes a number of OdfAttribute items to state which attributes to save.
     * @see saveOdf
215
     */
216
    void saveOdfAttributes(KoShapeSavingContext &context, int attributes) const;
217

Thorsten Zachmann's avatar
Thorsten Zachmann committed
218 219 220 221
    /**
     * This method can be used while saving the shape as Odf to add common child elements
     *
     * The office:event-listeners and draw:glue-point are saved.
222
     * @param context the context for the current save.
Thorsten Zachmann's avatar
Thorsten Zachmann committed
223
     */
224
    void saveOdfCommonChildElements(KoShapeSavingContext &context) const;
Thorsten Zachmann's avatar
Thorsten Zachmann committed
225

226 227 228 229 230 231 232 233 234
    /**
     * This method can be used to save contour data from the clipPath()
     *
     * The draw:contour-polygon or draw:contour-path elements are saved.
     * @param context the context for the current save.
     * @param originalSize the original size of the unscaled image.
     */
    void saveOdfClipContour(KoShapeSavingContext &context, const QSizeF &originalSize) const;

Thomas Zander's avatar
Thomas Zander committed
235 236 237 238 239 240 241
    /**
     * @brief Scale the shape using the zero-point which is the top-left corner.
     * @see position()
     *
     * @param sx scale in x direction
     * @param sy scale in y direction
     */
Thomas Zander's avatar
Thomas Zander committed
242
    void scale(qreal sx, qreal sy);
Thomas Zander's avatar
Thomas Zander committed
243 244

    /**
245
     * @brief Rotate the shape (relative)
Thomas Zander's avatar
Thomas Zander committed
246
     *
247
     * The shape will be rotated from the current rotation using the center of the shape using the size()
Thomas Zander's avatar
Thomas Zander committed
248
     *
249
     * @param angle change the angle of rotation increasing it with 'angle' degrees
Thomas Zander's avatar
Thomas Zander committed
250
     */
251
    void rotate(qreal angle);
Thomas Zander's avatar
Thomas Zander committed
252 253 254

    /**
     * Return the current rotation in degrees.
255
     * It returns NaN if the shape has a shearing or scaling transformation applied.
Thomas Zander's avatar
Thomas Zander committed
256
     */
257
    qreal rotation() const;
Thomas Zander's avatar
Thomas Zander committed
258 259 260 261 262 263 264 265 266

    /**
     * @brief Shear the shape
     * The shape will be sheared using the zero-point which is the top-left corner.
     * @see position()
     *
     * @param sx shear in x direction
     * @param sy shear in y direction
     */
Thomas Zander's avatar
Thomas Zander committed
267
    void shear(qreal sx, qreal sy);
Thomas Zander's avatar
Thomas Zander committed
268 269 270 271

    /**
     * @brief Resize the shape
     *
272
     * @param size the new size of the shape.  This is different from scaling as
Jan Hambrecht's avatar
Jan Hambrecht committed
273
     * scaling is a so called secondary operation which is comparable to zooming in
Thomas Zander's avatar
Thomas Zander committed
274 275
     * instead of changing the size of the basic shape.
     * Easiest example of this difference is that using this method will not distort the
276
     * size of pattern-fills and strokes.
Thomas Zander's avatar
Thomas Zander committed
277
     */
278
    virtual void setSize(const QSizeF &size);
Thomas Zander's avatar
Thomas Zander committed
279 280 281 282

    /**
     * @brief Get the size of the shape in pt.
     *
Thorsten Zachmann's avatar
Thorsten Zachmann committed
283 284
     * The size is in shape coordinates.
     *
Inge Wallin's avatar
Inge Wallin committed
285
     * @return the size of the shape as set by setSize()
Thomas Zander's avatar
Thomas Zander committed
286
     */
Thomas Zander's avatar
Thomas Zander committed
287
    virtual QSizeF size() const;
Thomas Zander's avatar
Thomas Zander committed
288 289 290 291 292 293

    /**
     * @brief Set the position of the shape in pt
     *
     * @param position the new position of the shape
     */
294
    virtual void setPosition(const QPointF &position);
Thomas Zander's avatar
Thomas Zander committed
295 296 297 298 299 300

    /**
     * @brief Get the position of the shape in pt
     *
     * @return the position of the shape
     */
301
    QPointF position() const;
Thomas Zander's avatar
Thomas Zander committed
302 303 304 305 306 307

    /**
     * @brief Check if the shape is hit on position
     * @param position the position where the user clicked.
     * @return true when it hits.
     */
308
    virtual bool hitTest(const QPointF &position) const;
Thomas Zander's avatar
Thomas Zander committed
309 310 311 312

    /**
     * @brief Get the bounding box of the shape
     *
313
     * This includes the line width and the shadow of the shape
Thomas Zander's avatar
Thomas Zander committed
314 315 316
     *
     * @return the bounding box of the shape
     */
317
    virtual QRectF boundingRect() const;
Thomas Zander's avatar
Thomas Zander committed
318 319 320

    /**
     * @brief Add a connector point to the shape
321
     *
Thomas Zander's avatar
Thomas Zander committed
322 323 324
     * A connector is a place on the shape that allows a graphical connection to be made
     * using a line, for example.
     *
325
     * @param point the connection point to add
326
     * @return the id of the new connection point
Thomas Zander's avatar
Thomas Zander committed
327
     */
328
    int addConnectionPoint(const KoConnectionPoint &point);
329

330
    /**
331
     * Sets data of connection point with specified id.
332 333
     *
     * The position of the connector is restricted to the bounding rectangle of the shape.
334 335 336 337
     * When setting a default connection point, the new position is ignored, as these
     * are fixed at their default position.
     * The function will insert a new connection point if the specified id was not used
     * before.
338
     *
339 340 341
     * @param connectionPointId the id of the connection point to set
     * @param point the connection point data
     * @return false if specified connection point id is invalid, else true
342
     */
343
    bool setConnectionPoint(int connectionPointId, const KoConnectionPoint &point);
344

345 346 347 348
    /// Checks if a connection point with the specified id exists
    bool hasConnectionPoint(int connectionPointId) const;

    /// Returns connection point with specified connection point id
349
    KoConnectionPoint connectionPoint(int connectionPointId) const;
Thomas Zander's avatar
Thomas Zander committed
350

351 352
    /**
     * Return a list of the connection points that have been added to this shape.
Thomas Zander's avatar
Thomas Zander committed
353
     * All the points are relative to the shape position, see absolutePosition().
354 355
     * @return a list of the connectors that have been added to this shape.
     */
356
    KoConnectionPoints connectionPoints() const;
Thomas Zander's avatar
Thomas Zander committed
357

358 359 360 361 362 363
    /// Removes connection point with specified id
    void removeConnectionPoint(int connectionPointId);

    /// Removes all connection points
    void clearConnectionPoints();

364
    /**
365
     * Add a event action
366
     */
367
    void addEventAction(KoEventAction *action);
368 369 370 371

    /**
     * Remove a event action
     */
372
    void removeEventAction(KoEventAction *action);
373 374 375 376

    /**
     * Get all event actions
     */
377
    QSet<KoEventAction *> eventActions() const;
378

379
    /**
Sebastian Sauer's avatar
dox++  
Sebastian Sauer committed
380 381
     * Return the side text should flow around this shape. This implements the ODF style:wrap
     * attribute that specifies how text is displayed around a frame or graphic object.
382 383 384 385 386 387
     */
    TextRunAroundSide textRunAroundSide() const;

    /**
     * Set the side text should flow around this shape.
     * @param side the requested side
Sebastian Sauer's avatar
dox++  
Sebastian Sauer committed
388
     * @param runThrought run through the foreground or background or...
389
     */
390
    void setTextRunAroundSide(TextRunAroundSide side, RunThroughLevel runThrough = Background);
391 392 393 394 395 396 397 398 399 400 401 402 403

    /**
     * The space between this shape's edge and text that runs around this shape.
     * @return the space around this shape to keep free from text
     */
    qreal textRunAroundDistance() const;

    /**
     * Set the space between this shape's edge and the text that run around this shape.
     * @param distance the space around this shape to keep free from text
     */
    void setTextRunAroundDistance(qreal distance);

404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419
    /**
     * Return the threshold above which text should flow around this shape.
     * The text will not flow around the shape on a side unless the space available on that side
     * is above this threshold. Only used when the text run around side is EnoughRunAroundSide.
     * @return threshold the threshold
     */
    qreal textRunAroundThreshold() const;

    /**
     * Set the threshold above which text should flow around this shape.
     * The text will not flow around the shape on a side unless the space available on that side
     * is above this threshold. Only used when the text run around side is EnoughRunAroundSide.
     * @param threshold the new threshold
     */
    void setTextRunAroundThreshold(qreal threshold);

420 421 422 423 424 425 426 427 428 429 430 431
    /**
     * Return the how tight text run around is done around this shape.
     * @return the contour
     */
    TextRunAroundContour textRunAroundContour() const;

    /**
     * Set how tight text run around is done around this shape.
     * @param contour the new contour
     */
    void setTextRunAroundContour(TextRunAroundContour contour);

Thomas Zander's avatar
Thomas Zander committed
432 433
    /**
     * Set the background of the shape.
434
     * A shape background can be a plain color, a gradient, a pattern, be fully transparent
Jan Hambrecht's avatar
Jan Hambrecht committed
435
     * or have a complex fill.
436
     * Setting such a background will allow the shape to be filled and will be able to tell
Jan Hambrecht's avatar
Jan Hambrecht committed
437 438
     * if it is transparent or not.
     * @param background the new shape background.
Thomas Zander's avatar
Thomas Zander committed
439
     */
440 441
    void setBackground(KoShapeBackground *background);

Thomas Zander's avatar
Thomas Zander committed
442 443
    /**
     * return the brush used to paint te background of this shape with.
444
     * A QBrush can have a plain color, be fully transparent or have a complex fill.
Thomas Zander's avatar
Thomas Zander committed
445
     * setting such a brush will allow the shape to fill itself using that brush and
446
     * will be able to tell if its transparent or not.
Thomas Zander's avatar
Thomas Zander committed
447 448
     * @return the background-brush
     */
449
    KoShapeBackground *background() const;
Thomas Zander's avatar
Thomas Zander committed
450 451

    /**
452 453
     * Returns true if there is some transparency, false if the shape is fully opaque.
     * The default implementation will just return if the background has some transparency,
Thomas Zander's avatar
Thomas Zander committed
454
     * you should override it and always return true if your shape is not square.
455
     * @return if the shape is (partly) transparent.
Thomas Zander's avatar
Thomas Zander committed
456
     */
Thomas Zander's avatar
Thomas Zander committed
457
    virtual bool hasTransparency() const;
Thomas Zander's avatar
Thomas Zander committed
458

459 460 461 462 463
    /**
     * Sets shape level transparency.
     * @param transparency the new shape level transparency
     */
    void setTransparency(qreal transparency);
464

465 466 467 468 469
    /**
     * Returns the shape level transparency.
     * @param recursive when true takes the parents transparency into account
     */
    qreal transparency(bool recursive=false) const;
470

Thomas Zander's avatar
Thomas Zander committed
471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486
    /**
     * Retrieve the z-coordinate of this shape.
     * The zIndex property is used to determine which shape lies on top of other objects.
     * An shape with a higher z-order is on top, and can obscure another shape.
     * @return the z-index of this shape.
     * @see setZIndex()
     */
    int zIndex() const;

    /**
     * Set the z-coordinate of this shape.
     * The zIndex property is used to determine which shape lies on top of other objects.
     * An shape with a higher z-order is on top, and can obscure, another shape.
     * <p>Just like two objects having the same x or y coordinate will make them 'touch',
     * so will two objects with the same z-index touch on the z plane.  In layering the
     * shape this, however, can cause a little confusion as one always has to be on top.
487
     * The layering if two overlapping objects have the same index is implementation dependent
Thomas Zander's avatar
Thomas Zander committed
488 489 490
     * and probably depends on the order in which they are added to the shape manager.
     * @param zIndex the new z-index;
     */
Thomas Zander's avatar
Thomas Zander committed
491
    void setZIndex(int zIndex);
Thomas Zander's avatar
Thomas Zander committed
492

493 494 495 496 497 498 499 500 501 502 503 504
    /**
     * Retrieve the run through property of this shape.
     * The run through property is used to determine if the shape is behind, inside or before text.
     * @return the run through of this shape.
     */
    int runThrough();

    /**
     * Set the run through property of this shape.
     * The run through property is used to determine if the shape is behind, inside or before text.
     * @param runThrough the new run through;
     */
Thorsten Zachmann's avatar
Thorsten Zachmann committed
505
    virtual void setRunThrough(short int runThrough);
506

Thomas Zander's avatar
Thomas Zander committed
507 508
    /**
     * Changes the Shape to be visible or invisible.
509
     * Being visible means being painted, as well as being used for
Thomas Zander's avatar
Thomas Zander committed
510 511
     *   things like guidelines or searches.
     * @param on when true; set the shape to be visible.
512
     * @see setGeometryProtected(), setContentProtected(), setSelectable()
Thomas Zander's avatar
Thomas Zander committed
513
     */
Thomas Zander's avatar
Thomas Zander committed
514
    void setVisible(bool on);
Thomas Zander's avatar
Thomas Zander committed
515 516
    /**
     * Returns current visibility state of this shape.
517
     * Being visible means being painted, as well as being used for
Thomas Zander's avatar
Thomas Zander committed
518
     *   things like guidelines or searches.
519
     * @param recursive when true, checks visibility recursively
Thomas Zander's avatar
Thomas Zander committed
520
     * @return current visibility state of this shape.
521
     * @see isGeometryProtected(), isContentProtected(), isSelectable()
Thomas Zander's avatar
Thomas Zander committed
522
     */
523
    bool isVisible(bool recursive = false) const;
Thomas Zander's avatar
Thomas Zander committed
524

525 526 527 528 529
    /**
     * Changes the shape to be printable or not. The default is true.
     *
     * If a Shape's print flag is true, the shape will be printed. If
     * false, the shape will not be printed. If a shape is not visible (@see isVisible),
530
     * it isPrinted will return false, too.
531 532 533 534 535 536 537 538 539 540 541 542
     */
    void setPrintable(bool on);

    /**
     * Returns the current printable state of this shape.
     *
     * A shape can be visible but not printable, not printable and not visible
     * or visible and printable, but not invisible and still printable.
     *
     * @return current printable state of this shape.
     */
    bool isPrintable() const;
543

544 545 546
    /**
     * Makes it possible for the user to select this shape.
     * This parameter defaults to true.
Thomas Zander's avatar
Thomas Zander committed
547
     * @param selectable when true; set the shape to be selectable by the user.
548
     * @see setGeometryProtected(), setContentProtected(), setVisible()
549
     */
Thomas Zander's avatar
Thomas Zander committed
550
    void setSelectable(bool selectable);
551

552
    /**
Thomas Zander's avatar
Thomas Zander committed
553
     * Returns if this shape can be selected by the user.
554
     * @return true only when the object is selectable.
555
     * @see isGeometryProtected(), isContentProtected(), isVisible()
556
     */
Thomas Zander's avatar
Thomas Zander committed
557
    bool isSelectable() const;
558

Thomas Zander's avatar
Thomas Zander committed
559
    /**
560 561 562 563
     * Tells the shape to have its position/rotation and size protected from user-changes.
     * The geometry being protected means the user can not change shape or position of the
     * shape. This includes any matrix operation such as rotation.
     * @param on when true; set the shape to have its geometry protected.
564
     * @see setContentProtected(), setSelectable(), setVisible()
Thomas Zander's avatar
Thomas Zander committed
565
     */
566
    void setGeometryProtected(bool on);
567

Thomas Zander's avatar
Thomas Zander committed
568
    /**
569 570 571 572
     * Returns current geometry protection state of this shape.
     * The geometry being protected means the user can not change shape or position of the
     * shape. This includes any matrix operation such as rotation.
     * @return current geometry protection state of this shape.
573
     * @see isContentProtected(), isSelectable(), isVisible()
Thomas Zander's avatar
Thomas Zander committed
574
     */
575
    bool isGeometryProtected() const;
Thomas Zander's avatar
Thomas Zander committed
576

577 578 579 580
    /**
     * Marks the shape to have its content protected against editing.
     * Content protection is a hint for tools to disallow the user editing the content.
     * @param protect when true set the shapes content to be protected from user modification.
581
     * @see setGeometryProtected(), setSelectable(), setVisible()
582 583
     */
    void setContentProtected(bool protect);
584

585 586 587 588
    /**
     * Returns current content protection state of this shape.
     * Content protection is a hint for tools to disallow the user editing the content.
     * @return current content protection state of this shape.
589
     * @see isGeometryProtected(), isSelectable(), isVisible()
590 591 592
     */
    bool isContentProtected() const;

Thomas Zander's avatar
Thomas Zander committed
593 594 595 596
    /**
     * Returns the parent, or 0 if there is no parent.
     * @return the parent, or 0 if there is no parent.
     */
Thomas Zander's avatar
Thomas Zander committed
597
    KoShapeContainer *parent() const;
Thomas Zander's avatar
Thomas Zander committed
598 599 600 601 602 603 604 605 606 607 608 609 610 611

    /**
     * Set the parent of this shape.
     * @param parent the new parent of this shape. Can be 0 if the shape has no parent anymore.
     */
    void setParent(KoShapeContainer *parent);

    /**
     * Request a repaint to be queued.
     * The repaint will be of the entire Shape, including its selection handles should this
     * shape be selected.
     * <p>This method will return immediately and only request a repaint. Successive calls
     * will be merged into an appropriate repaint action.
     */
612
    virtual void update() const;
Thomas Zander's avatar
Thomas Zander committed
613 614 615 616 617 618 619 620

    /**
     * Request a repaint to be queued.
     * The repaint will be restricted to the parameters rectangle, which is expected to be
     * in points (the internal coordinates system of KoShape) and it is expected to be
     * normalized.
     * <p>This method will return immediately and only request a repaint. Successive calls
     * will be merged into an appropriate repaint action.
Boudewijn Rempt's avatar
Boudewijn Rempt committed
621
     * @param rect the rectangle (in pt) to queue for repaint.
Thomas Zander's avatar
Thomas Zander committed
622
     */
Boudewijn Rempt's avatar
Boudewijn Rempt committed
623
    virtual void update(const QRectF &rect) const;
Thomas Zander's avatar
Thomas Zander committed
624

625 626 627 628 629 630 631
    /// Used by compareShapeZIndex() to order shapes
    enum ChildZOrderPolicy {
        ChildZDefault,
        ChildZParentChild = ChildZDefault, ///< normal parent/child ordering
        ChildZPassThrough ///< children are considered equal to this shape
    };

632
   /**
633 634 635 636 637 638 639 640
    * Returns if during compareShapeZIndex() how this shape portrays the values
    * of its children. The default behaviour is to let this shape's z values take
    * the place of its childrens values, so you get a parent/child relationship.
    * The children are naturally still ordered relatively to their z values
    *
    * But for special cases (like Calligra's TextShape) it can be overloaded to return
    * ChildZPassThrough which means the children keep their own z values
    * @returns the z order policy of this shape
641
    */
642
    virtual ChildZOrderPolicy childZOrderPolicy();
643

Thomas Zander's avatar
Thomas Zander committed
644 645
    /**
     * This is a method used to sort a list using the STL sorting methods.
646 647
     * @param s1 the first shape
     * @param s2 the second shape
Thomas Zander's avatar
Thomas Zander committed
648
     */
649
    static bool compareShapeZIndex(KoShape *s1, KoShape *s2);
Thomas Zander's avatar
Thomas Zander committed
650 651 652

    /**
     * returns the outline of the shape in the form of a path.
Casper Boemann's avatar
Casper Boemann committed
653
     * The outline returned will always be relative to the position() of the shape, so
654
     * moving the shape will not alter the result.  The outline is used to draw the stroke
Thomas Zander's avatar
Thomas Zander committed
655 656 657
     * on, for example.
     * @returns the outline of the shape in the form of a path.
     */
658
    virtual QPainterPath outline() const;
Thomas Zander's avatar
Thomas Zander committed
659

660 661
    /**
     * returns the outline of the shape in the form of a rect.
Casper Boemann's avatar
Casper Boemann committed
662 663 664
     * The outlineRect returned will always be relative to the position() of the shape, so
     * moving the shape will not alter the result.  The outline is used to calculate
     * the boundingRect.
665 666 667 668
     * @returns the outline of the shape in the form of a rect.
     */
    virtual QRectF outlineRect() const;

669 670 671 672 673 674 675 676 677 678 679 680
    /**
     * returns the outline of the shape in the form of a path for the use of painting a shadow.
     *
     * Normally this would be the same as outline() if there is a fill (background) set on the
     * shape and empty if not.  However, a shape could reimplement this to return an outline
     * even if no fill is defined. A typical example of this would be the picture shape
     * which has a picture but almost never a background. 
     *
     * @returns the outline of the shape in the form of a path.
     */
    virtual QPainterPath shadowOutline() const;

Thomas Zander's avatar
Thomas Zander committed
681
    /**
682 683
     * Returns the currently set stroke, or 0 if there is no stroke.
     * @return the currently set stroke, or 0 if there is no stroke.
Thomas Zander's avatar
Thomas Zander committed
684
     */
685
    KoShapeStrokeModel *stroke() const;
Thomas Zander's avatar
Thomas Zander committed
686 687

    /**
688 689
     * Set a new stroke, removing the old one.
     * @param stroke the new stroke, or 0 if there should be no stroke.
Thomas Zander's avatar
Thomas Zander committed
690
     */
691
    void setStroke(KoShapeStrokeModel *stroke);
Thomas Zander's avatar
Thomas Zander committed
692

693
    /**
694 695
     * Return the insets of the stroke.
     * Convenience method for KoShapeStrokeModel::strokeInsets()
696
     */
697
    KoInsets strokeInsets() const;
698

699
    /// Sets the new shadow, removing the old one
700
    void setShadow(KoShapeShadow *shadow);
701

702
    /// Returns the currently set shadow or 0 if there is no shadow set
703
    KoShapeShadow *shadow() const;
704

705
    /// Sets a new clip path, removing the old one
Jan Hambrecht's avatar
Jan Hambrecht committed
706
    void setClipPath(KoClipPath *clipPath);
707 708 709 710

    /// Returns the currently set clip path or 0 if there is no clip path set
    KoClipPath * clipPath() const;

Thomas Zander's avatar
Thomas Zander committed
711 712 713 714 715 716
    /**
     * Setting the shape to keep its aspect-ratio has the effect that user-scaling will
     * keep the width/hight ratio intact so as not to distort shapes that rely on that
     * ratio.
     * @param keepAspect the new value
     */
Thomas Zander's avatar
Thomas Zander committed
717
    void setKeepAspectRatio(bool keepAspect);
718

Thomas Zander's avatar
Thomas Zander committed
719 720 721 722 723 724
    /**
     * Setting the shape to keep its aspect-ratio has the effect that user-scaling will
     * keep the width/hight ratio intact so as not to distort shapes that rely on that
     * ratio.
     * @return whether to keep aspect ratio of this shape
     */
Thomas Zander's avatar
Thomas Zander committed
725
    bool keepAspectRatio() const;
Thomas Zander's avatar
Thomas Zander committed
726 727 728 729

    /**
     * Return the position of this shape regardless of rotation/skew/scaling and regardless of
     * this shape having a parent (being in a group) or not.<br>
730
     * @param anchor The place on the (unaltered) shape that you want the position of.
Thomas Zander's avatar
Thomas Zander committed
731 732
     * @return the point that is the absolute, centered position of this shape.
     */
Jan Hambrecht's avatar
Jan Hambrecht committed
733
    QPointF absolutePosition(KoFlake::Position anchor = KoFlake::CenteredPosition) const;
734

Thomas Zander's avatar
Thomas Zander committed
735 736 737 738 739 740 741 742 743 744 745 746
    /**
     * Move this shape to an absolute position where the end location will be the same
     * regardless of the shape's rotation/skew/scaling and regardless of this shape having
     * a parent (being in a group) or not.<br>
     * The newPosition is going to be the center of the shape.
     * This has the convenient effect that: <pre>
    shape-&gt;setAbsolutePosition(QPointF(0,0));
    shape-&gt;rotate(45);</pre>
        Will result in the same visual position of the shape as the opposite:<pre>
    shape-&gt;rotate(45);
    shape-&gt;setAbsolutePosition(QPointF(0,0));</pre>
     * @param newPosition the new absolute center of the shape.
Thomas Zander's avatar
Thomas Zander committed
747
     * @param anchor The place on the (unaltered) shape that you set the position of.
Thomas Zander's avatar
Thomas Zander committed
748
     */
Jan Hambrecht's avatar
Jan Hambrecht committed
749
    void setAbsolutePosition(QPointF newPosition, KoFlake::Position anchor = KoFlake::CenteredPosition);
Thomas Zander's avatar
Thomas Zander committed
750

751 752
    /**
     * Set a data object on the shape to be used by an application.
753
     * This is specifically useful when a shape is created in a plugin and that data from that
754 755 756 757 758 759 760 761 762
     * shape should be accessible outside the plugin.
     * @param userData the new user data, or 0 to delete the current one.
     */
    void setUserData(KoShapeUserData *userData);
    /**
     * Return the current userData.
     */
    KoShapeUserData *userData() const;

763 764 765 766 767 768 769
    /**
     * Set a data object on the shape to be used by an application.
     * This is specifically useful when an application wants to have data that is per shape
     * and should be deleted when the shape is destructed.
     * @param applicationData the new application data, or 0 to delete the current one.
     */
    void setApplicationData(KoShapeApplicationData *applicationData);
770

771 772 773 774 775
    /**
     * Return the current applicationData.
     */
    KoShapeApplicationData *applicationData() const;

776
    /**
Marijn Kruisselbrink's avatar
Marijn Kruisselbrink committed
777
     * Return the Id of this shape, identifying the type of shape by the id of the factory.
778
     * @see KoShapeFactoryBase::shapeId()
779 780
     * @return the id of the shape-type
     */
781 782
    QString shapeId() const;

783 784 785
    /**
     * Set the Id of this shape.  A shapeFactory is expected to set the Id at creation
     * so applications can find out what kind of shape this is.
786
     * @see KoShapeFactoryBase::shapeId()
787 788
     * @param id the ID from the factory that created this shape
     */
Thomas Zander's avatar
Thomas Zander committed
789
    void setShapeId(const QString &id);
790

Thomas Zander's avatar
Thomas Zander committed
791 792
    /**
     * Create a matrix that describes all the transformations done on this shape.
793 794 795 796
     *
     * The absolute transformation is the combined transformation of this shape
     * and all its parents and grandparents.
     *
Thomas Zander's avatar
Thomas Zander committed
797 798 799
     * @param converter if not null, this method uses the converter to mark the right
     *        offsets in the current view.
     */
800
    QTransform absoluteTransformation(const KoViewConverter *converter) const;
Thomas Zander's avatar
Thomas Zander committed
801

802 803 804 805
    /**
     * Applies a transformation to this shape.
     *
     * The transformation given is relative to the global coordinate system, i.e. the document.
806 807
     * This is a convenience function to apply a global transformation to this shape.
     * @see applyTransformation
808 809 810
     *
     * @param matrix the transformation matrix to apply
     */
811
    void applyAbsoluteTransformation(const QTransform &matrix);
812 813 814 815 816

    /**
     * Sets a new transformation matrix describing the local transformations on this shape.
     * @param matrix the new transformation matrix
     */
817
    void setTransformation(const QTransform &matrix);
818

819
    /// Returns the shapes local transformation matrix
820
    QTransform transformation() const;
821 822 823 824 825 826 827 828

    /**
     * Applies a transformation to this shape.
     *
     * The transformation given is relative to the shape coordinate system.
     *
     * @param matrix the transformation matrix to apply
     */
829
    void applyTransformation(const QTransform &matrix);
830

Thomas Zander's avatar
Thomas Zander committed
831 832 833 834 835 836
    /**
     * Copy all the settings from the parameter shape and apply them to this shape.
     * Settings like the position and rotation to visible and locked.  The parent
     * is a notable exclusion.
     * @param shape the shape to use as original
     */
Thomas Zander's avatar
Thomas Zander committed
837
    void copySettings(const KoShape *shape);
Thomas Zander's avatar
Thomas Zander committed
838

Thomas Zander's avatar
Thomas Zander committed
839 840 841 842 843 844 845 846 847
    /**
     * Convenience method that allows people implementing paint() to use the shape
     * internal coordinate system directly to paint itself instead of considering the
     * views zoom.
     * @param painter the painter to alter the zoom level of.
     * @param converter the converter for the current views zoom.
     */
    static void applyConversion(QPainter &painter, const KoViewConverter &converter);

848 849 850 851 852
    /**
     * @brief Transforms point from shape coordinates to document coordinates
     * @param point in shape coordinates
     * @return point in document coordinates
     */
853
    QPointF shapeToDocument(const QPointF &point) const;
854 855 856 857 858 859

    /**
     * @brief Transforms rect from shape coordinates to document coordinates
     * @param rect in shape coordinates
     * @return rect in document coordinates
     */
860
    QRectF shapeToDocument(const QRectF &rect) const;
861 862 863 864 865 866

    /**
     * @brief Transforms point from document coordinates to shape coordinates
     * @param point in document coordinates
     * @return point in shape coordinates
     */
867
    QPointF documentToShape(const QPointF &point) const;
868 869 870 871 872 873

    /**
     * @brief Transform rect from document coordinates to shape coordinates
     * @param rect in document coordinates
     * @return rect in shape coordinates
     */
874
    QRectF documentToShape(const QRectF &rect) const;
875

876 877 878 879
    /**
     * Returns the name of the shape.
     * @return the shapes name
     */
880
    QString name() const;
881 882 883 884 885

    /**
     * Sets the name of the shape.
     * @param name the new shape name
     */
886
    void setName(const QString &name);
887

888 889 890 891 892
    /**
     * Update the position of the shape in the tree of the KoShapeManager.
     */
    void notifyChanged();

893
    /**
Thomas Zander's avatar
Thomas Zander committed
894
     * A shape can be in a state that it is doing processing data like loading or text layout.
895
     * In this case it can be shown on screen probably partially but it should really not be printed
Thomas Zander's avatar
Thomas Zander committed
896
     * until it is fully done processing.
897
     * Warning! This method can be blocking for a long time
Boudewijn Rempt's avatar
Boudewijn Rempt committed
898 899 900
     * @param asynchronous If set to true the processing will can take place in a different thread and the
     *                     function will not block until the shape is finised.
     *                     In case of printing Flake will call this method from a non-main thread and only
901
     *                     start printing it when the in case of printing method returned.
Boudewijn Rempt's avatar
Boudewijn Rempt committed
902
     *                     If set to false the processing needs to be done synchronously and will
903 904 905
     *                     block until the result is finished.
     */
    virtual void waitUntilReady(const KoViewConverter &converter, bool asynchronous = true) const;
906

Thomas Zander's avatar
api dox  
Thomas Zander committed
907 908 909
    /**
     * Schedule the shape for thread-safe deletion.
     * After calling this method will self-delete in the main threads event loop.
Thomas Zander's avatar
Thomas Zander committed
910 911 912 913
     * If your code deletes a shape and your code can possibly be running in a separate thread,
     * you should use this method to delete the shape.
     * The reason for this is that If you delete a shape from another thread then it is
     * possible the main
Thomas Zander's avatar
api dox  
Thomas Zander committed
914
     * thread will use it after its been removed, while painting for example.
Thomas Zander's avatar
Thomas Zander committed
915 916
     *
     * Note that in contrary to the equivalent method on QObject, you can not call this more than once.
Thomas Zander's avatar
api dox  
Thomas Zander committed
917
     */
918
    void deleteLater();
919

920 921 922
    /// checks recursively if the shape or one of its parents is not visible or locked
    bool isEditable() const;

923 924
    /**
     * Adds a shape which depends on this shape.
925 926
     * Making a shape dependent on this one means it will get shapeChanged() called
     * on each update of this shape.
927 928 929 930 931
     *
     * If this shape already depends on the given shape, establishing the
     * dependency is refused to prevent circular dependencies.
     *
     * @param shape the shape which depends on this shape
932 933
     * @return true if dependency could be established, otherwise false
     * @see removeDependee(), hasDependee()
934
     */
935
    bool addDependee(KoShape *shape);
936

937 938 939 940
    /**
     * Removes as shape depending on this shape.
     * @see addDependee(), hasDependee()
     */
941
    void removeDependee(KoShape *shape);
942

943
    /// Returns if the given shape is dependent on this shape
944
    bool hasDependee(KoShape *shape) const;
945

946 947 948
    /// Returns list of shapes depending on this shape
    QList<KoShape*> dependees() const;

949 950 951
    /// Returns additional snap data the shape wants to have snapping to
    virtual KoSnapData snapData() const;

952 953 954 955 956 957 958 959 960
    /**
     * Set additional attribute
     *
     * This can be used to attach additional attributes to a shape for attributes
     * that are application specific like presentation:placeholder
     *
     * @param name The name of the attribute in the following form prefix:tag e.g. presentation:placeholder
     * @param value The value of the attribute
     */
961
    void setAdditionalAttribute(const QString &name, const QString &value);
962 963 964 965 966 967

    /**
     * Remove additional attribute
     *
     * @param name The name of the attribute in the following form prefix:tag e.g. presentation:placeholder
     */
968
    void removeAdditionalAttribute(const QString &name);
969 970 971 972 973 974 975 976

    /**
     * Check if additional attribute is set
     *
     * @param name The name of the attribute in the following form prefix:tag e.g. presentation:placeholder
     *
     * @return true if there is a attribute with prefix:tag set, false otherwise
     */
977
    bool hasAdditionalAttribute(const QString &name) const;
978 979 980 981 982 983 984 985

    /**
     * Get additional attribute
     *
     * @param name The name of the attribute in the following form prefix:tag e.g. presentation:placeholder
     *
     * @return The value of the attribute if it exists or a null string if not found.
     */
986
    QString additionalAttribute(const QString &name) const;
987

988
    void setAdditionalStyleAttribute(const char *name, const QString &value);
989

990
    void removeAdditionalStyleAttribute(const char *name);
991

992
    /**
993
     * Returns the filter effect stack of the shape
994 995 996
     *
     * @return the list of filter effects applied on the shape when rendering.
     */
997
    KoFilterEffectStack *filterEffectStack() const;
998

999
    /// Sets the new filter effect stack, removing the old one
1000
    void setFilterEffectStack(KoFilterEffectStack *filterEffectStack);
1001

1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015
    /**
     * Set the property collision detection.
     * Setting this to true will result in calls to shapeChanged() with the CollisionDetected
     * parameter whenever either this or another shape is moved/rotated etc and intersects this shape.
     * @param detect if true detect collisions.
     */
    void setCollisionDetection(bool detect);

    /**
     * get the property collision detection.
     * @returns true if collision detection is on.
     */
    bool collisionDetection();

1016 1017 1018 1019 1020 1021
    /**
     * Return the tool delegates for this shape.
     * In Flake a shape being selected will cause the tool manager to make available all tools that
     * can edit the selected shapes.  In some cases selecting one shape should allow the tool to
     * edit a related shape be available too.  The tool delegates allows this to happen by taking
     * all the shapes in the set into account on tool selection.
Thomas Zander's avatar
Thomas Zander committed
1022
     * Notice that if the set is non-empty 'this' shape is no longer looked at. You can choose
1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033
     * to add itself to the set too.
     */
    QSet<KoShape*> toolDelegates() const;

    /**
     * Set the tool delegates.
     * @param delegates the new delegates.
     * @see toolDelegates()
     */
    void setToolDelegates(const QSet<KoShape*> &delegates);

1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044
    /**
     * Return the hyperlink for this shape.
     */
    QString hyperLink () const;

    /**
     * Set hyperlink for this shape.
     * @param hyperLink name.
     */
    void setHyperLink (QString & hyperLink);

1045 1046
    /**
     * \internal
Marijn Kruisselbrink's avatar
Marijn Kruisselbrink committed
1047
     * Returns the private object for use within the flake lib
1048 1049 1050
     */
    KoShapePrivate *priv();

1051
protected:
1052 1053
    /// constructor
    KoShape(KoShapePrivate &);
1054

1055
    /* ** loading saving helper methods */
1056 1057
    /// attributes from ODF 1.1 chapter 9.2.15 Common Drawing Shape Attributes
    enum OdfAttribute {
1058 1059
        OdfTransformation = 1,       ///< Store transformation information
        OdfSize = 2,                 ///< Store size information
1060 1061 1062 1063 1064 1065 1066
        OdfPosition = 8,             ///< Store position
        OdfAdditionalAttributes = 4, ///< Store additional attributes of the shape
        OdfCommonChildElements = 16, ///< Event actions and connection points
        OdfLayer = 64,               ///< Store layer name
        OdfStyle = 128,              ///< Store the style
        OdfId = 256,                 ///< Store the unique ID
        OdfName = 512,               ///< Store the name of the shape
1067
        OdfZIndex = 1024,            ///< Store the z-index
1068
        OdfViewbox = 2048,           ///< Store the viewbox
1069 1070 1071 1072 1073

        /// A mask for all mandatory attributes
        OdfMandatories = OdfLayer | OdfStyle | OdfId | OdfName | OdfZIndex,
        /// A mask for geometry attributes
        OdfGeometry = OdfPosition | OdfSize,
1074
        /// A mask for all the attributes
1075
        OdfAllAttributes = OdfTransformation | OdfGeometry | OdfAdditionalAttributes | OdfMandatories | OdfCommonChildElements
1076
    };
1077

1078 1079 1080 1081 1082 1083 1084
    /**
     * This method is used during loading of the shape to load common attributes
     *
     * @param context the KoShapeLoadingContext used for loading
     * @param element element which represents the shape in odf
     * @param attributes a number of OdfAttribute items to state which attributes to load.
     */
1085
    bool loadOdfAttributes(const KoXmlElement &element, KoShapeLoadingContext &context, int attributes);
1086

Jan Hambrecht's avatar
 
Jan Hambrecht committed
1087 1088 1089 1090 1091
    /**
     * Parses the transformation attribute from the given string
     * @param transform the transform attribute string
     * @return the resulting transformation matrix
     */
1092
    QTransform parseOdfTransform(const QString &transform);
Jan Hambrecht's avatar
 
Jan Hambrecht committed
1093

1094
    /**
1095
     * @brief Saves the style used for the shape