KoShape.h 34.8 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-2009 Thomas Zander <zander@kde.org>
5
   Copyright (C) 2007-2009 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

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

36
#include <KoXmlReaderForward.h>
37
#include <KoSnapData.h>
38

39 40
#include "flake_export.h"

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

class KoShapeContainer;
class KoShapeBorderModel;
47
class KoShapeBackground;
48
class KoShapeManager;
49
class KoShapeUserData;
50
class KoViewConverter;
51
class KoShapeApplicationData;
52
class KoShapeSavingContext;
53
class KoCanvasBase;
54
class KoShapeLoadingContext;
55
class KoGenStyle;
56
class KoShapeControllerBase;
57
class KoDataCenter;
58
class KoShapeShadow;
59
class KoEventAction;
60
class KoShapePrivate;
61
class KoFilterEffect;
Thomas Zander's avatar
Thomas Zander committed
62 63

/**
64
 *
65
 * Base class for all flake shapes. Shapes extend this class
Thomas Zander's avatar
Thomas Zander committed
66 67 68
 * 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.
69
 *
70
 * Due to the limited responsibility of this class, the extending object
Thomas Zander's avatar
Thomas Zander committed
71
 * can have any data backend and is responsible for painting itself.
72
 *
73
 * We strongly suggest that any extending class will use a Model View
Thomas Zander's avatar
Thomas Zander committed
74
 * Controller (MVC) design where the View part is all in this class, as well
75
 * as the one that inherits from this one.  This allows the data that rests
Thomas Zander's avatar
Thomas Zander committed
76
 * in the model to be reused in different parts of the document. For example
77
 * by having two flake objects that show that same data. Or each showing a section of it.
78
 *
79 80 81 82 83
 * 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()
84
 *
85
 * <p>Flake objects can be created in three ways:
86 87 88 89 90
 * <ul>
 *   <li>a simple new KoDerivedFlake(),
 *   <li>through an associated tool,
 *   <li>through a factory
 * </ul>
91
 *
Thomas Zander's avatar
Thomas Zander committed
92 93 94 95 96 97 98 99 100 101 102 103 104
 * <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
105
 */
106
class FLAKE_EXPORT KoShape
Thomas Zander's avatar
Thomas Zander committed
107 108
{
public:
109 110 111
    /// Used by shapeChanged() to select which change was made
    enum ChangeType {
        PositionChanged, ///< used after a setPosition()
112 113 114 115
        RotationChanged, ///< used after a setRotation()
        ScaleChanged,   ///< used after a setScale()
        ShearChanged,   ///< used after a setShear()
        SizeChanged,    ///< used after a setSize()
116
        GenericMatrixChange,    ///< used after the matrix was changed without knowing which property explicitly changed
117
        ParentChanged,   ///< used after a setParent()
118
        CollisionDetected, ///< used when another shape moved in our boundingrect
119 120
        Deleted, ///< the shape was deleted
        BorderChanged, ///< the shapes border has changed
121
        BackgroundChanged, ///< the shapes background has changed
122 123
        ShadowChanged, ///< the shapes shadow has changed
        ParameterChanged ///< the shapes parameter has changed (KoParameterShape only)
124 125
    };

Thomas Zander's avatar
Thomas Zander committed
126 127 128 129 130 131 132 133 134 135 136 137 138 139
    /**
     * @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
140
     * something transparent on top.
Thomas Zander's avatar
Thomas Zander committed
141 142 143 144
     * 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.
145 146
     * 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
147 148 149 150
     * @param painter used for painting the shape
     * @param converter to convert between internal and view coordinates.
     * @see applyConversion()
     */
151
    virtual void paint(QPainter &painter, const KoViewConverter &converter) = 0;
Thomas Zander's avatar
Thomas Zander committed
152 153 154 155 156 157 158

    /**
     * Paint non-print decorations specific for this type of shape.
     * The default implementation is empty.
     *
     * @param painter used for painting the shape
     * @param converter to convert between internal and view coordinates.
Thomas Zander's avatar
Thomas Zander committed
159 160
     * @param canvas the canvas that requested this paint.  This can be used to retrieve canvas specific properties
     *      like selection and get a reference to the KoCanvasResourceProvider.
Thomas Zander's avatar
Thomas Zander committed
161
     */
162
    virtual void paintDecorations(QPainter &painter, const KoViewConverter &converter, const KoCanvasBase *canvas);
Thomas Zander's avatar
Thomas Zander committed
163

164 165 166 167 168 169
    /**
     * Load a shape from odf
     *
     * @param context the KoShapeLoadingContext used for loading
     * @param element element which represents the shape in odf
     *
170
     * @return false if loading failed
171
     */
172
    virtual bool loadOdf(const KoXmlElement & element, KoShapeLoadingContext &context) = 0;
173

174
    /**
175
     * @brief store the shape data as ODF XML.
Thomas Zander's avatar
fix dox  
Thomas Zander committed
176
     * This is the method that will be called when saving a shape as a described in
177
     * OpenDocument 9.2 Drawing Shapes.
Thorsten Zachmann's avatar
Thorsten Zachmann committed
178
     * @see saveOdfAttributes
179
     */
180
    virtual void saveOdf(KoShapeSavingContext & context) const = 0;
181 182

    /**
183 184 185 186 187 188
     * 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
189
     */
190
    void saveOdfAttributes(KoShapeSavingContext &context, int attributes) const;
191

Thorsten Zachmann's avatar
Thorsten Zachmann committed
192 193 194 195 196
    /**
     * 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.
     */
197
    void saveOdfCommonChildElements(KoShapeSavingContext &context) const;
Thorsten Zachmann's avatar
Thorsten Zachmann committed
198

199 200 201 202 203
    /**
     * After the shape has been created this method is called so it can get access to any DataCenter it
     * might want.
     * The default implementation does nothing.
     */
204
    virtual void init(const QMap<QString, KoDataCenter *> & dataCenterMap);
205

Thomas Zander's avatar
Thomas Zander committed
206 207 208 209 210 211 212
    /**
     * @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
     */
213
    void setScale(qreal sx, qreal sy);
Thomas Zander's avatar
Thomas Zander committed
214 215

    /**
216
     * @brief Rotate the shape (relative)
Thomas Zander's avatar
Thomas Zander committed
217
     *
218
     * 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
219
     *
220
     * @param angle change the angle of rotation increasing it with 'angle' degrees
Thomas Zander's avatar
Thomas Zander committed
221
     */
222
    void rotate(qreal angle);
Thomas Zander's avatar
Thomas Zander committed
223 224 225

    /**
     * Return the current rotation in degrees.
226
     * It returns NaN if the shape has a shearing or scaling transformation applied.
Thomas Zander's avatar
Thomas Zander committed
227
     */
228
    qreal rotation() const;
Thomas Zander's avatar
Thomas Zander committed
229 230 231 232 233 234 235 236 237

    /**
     * @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
     */
238
    void setShear(qreal sx, qreal sy);
Thomas Zander's avatar
Thomas Zander committed
239 240 241 242

    /**
     * @brief Resize the shape
     *
243
     * @param size the new size of the shape.  This is different from scaling as
Jan Hambrecht's avatar
Jan Hambrecht committed
244
     * scaling is a so called secondary operation which is comparable to zooming in
Thomas Zander's avatar
Thomas Zander committed
245 246 247 248
     * instead of changing the size of the basic shape.
     * Easiest example of this difference is that using this method will not distort the
     * size of pattern-fills and borders.
     */
249
    virtual void setSize(const QSizeF &size);
Thomas Zander's avatar
Thomas Zander committed
250 251 252 253

    /**
     * @brief Get the size of the shape in pt.
     *
Thorsten Zachmann's avatar
Thorsten Zachmann committed
254 255
     * The size is in shape coordinates.
     *
Thomas Zander's avatar
Thomas Zander committed
256 257
     * @return the size of the shape as set by resize()
     */
Thomas Zander's avatar
Thomas Zander committed
258
    virtual QSizeF size() const;
Thomas Zander's avatar
Thomas Zander committed
259 260 261 262 263 264

    /**
     * @brief Set the position of the shape in pt
     *
     * @param position the new position of the shape
     */
265
    virtual void setPosition(const QPointF &position);
Thomas Zander's avatar
Thomas Zander committed
266 267 268 269 270 271

    /**
     * @brief Get the position of the shape in pt
     *
     * @return the position of the shape
     */
272
    QPointF position() const;
Thomas Zander's avatar
Thomas Zander committed
273 274 275 276 277 278

    /**
     * @brief Check if the shape is hit on position
     * @param position the position where the user clicked.
     * @return true when it hits.
     */
279
    virtual bool hitTest(const QPointF &position) const;
Thomas Zander's avatar
Thomas Zander committed
280 281 282 283 284 285 286 287

    /**
     * @brief Get the bounding box of the shape
     *
     * This includes the line width but not the shadow of the shape
     *
     * @return the bounding box of the shape
     */
288
    virtual QRectF boundingRect() const;
Thomas Zander's avatar
Thomas Zander committed
289 290 291 292 293 294 295 296 297 298 299

    /**
     * @brief Add a connector point to the shape
     * A connector is a place on the shape that allows a graphical connection to be made
     * using a line, for example.
     *
     * @param point the position where to place the connector. The points coordinate system
     *   are based around the zero-pos which is the top-left of the shape
     *   The point does not have to be inside the boundings rectangle.  The point is in pt,
     *   just like the rest of the KoShape class uses.
     */
300
    void addConnectionPoint(const QPointF &point);
Thomas Zander's avatar
Thomas Zander committed
301

302 303
    /**
     * Return a list of the connection points that have been added to this shape.
Thomas Zander's avatar
Thomas Zander committed
304
     * All the points are relative to the shape position, see absolutePosition().
305 306
     * @return a list of the connectors that have been added to this shape.
     */
307
    QList<QPointF> connectionPoints() const;
Thomas Zander's avatar
Thomas Zander committed
308

309
    /**
310
     * Add a event action
311
     */
312
    void addEventAction(KoEventAction * action);
313 314 315 316

    /**
     * Remove a event action
     */
317
    void removeEventAction(KoEventAction * action);
318 319 320 321 322 323

    /**
     * Get all event actions
     */
    QList<KoEventAction *> eventActions() const;

Thomas Zander's avatar
Thomas Zander committed
324 325
    /**
     * Set the background of the shape.
326
     * A shape background can be a plain color, a gradient, a pattern, be fully transparent
Jan Hambrecht's avatar
Jan Hambrecht committed
327
     * or have a complex fill.
328
     * Setting such a background will allow the shape to be filled and will be able to tell
Jan Hambrecht's avatar
Jan Hambrecht committed
329 330
     * if it is transparent or not.
     * @param background the new shape background.
Thomas Zander's avatar
Thomas Zander committed
331
     */
332
    void setBackground(KoShapeBackground * background);
Thomas Zander's avatar
Thomas Zander committed
333 334
    /**
     * return the brush used to paint te background of this shape with.
335
     * A QBrush can have a plain color, be fully transparent or have a complex fill.
Thomas Zander's avatar
Thomas Zander committed
336
     * setting such a brush will allow the shape to fill itself using that brush and
337
     * will be able to tell if its transparent or not.
Thomas Zander's avatar
Thomas Zander committed
338 339
     * @return the background-brush
     */
340
    KoShapeBackground * background() const;
Thomas Zander's avatar
Thomas Zander committed
341 342

    /**
343 344
     * 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
345
     * you should override it and always return true if your shape is not square.
346
     * @return if the shape is (partly) transparent.
Thomas Zander's avatar
Thomas Zander committed
347
     */
348
    virtual bool hasTransparency();
Thomas Zander's avatar
Thomas Zander committed
349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365

    /**
     * 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.
366
     * The layering if two overlapping objects have the same index is implementation dependent
Thomas Zander's avatar
Thomas Zander committed
367 368 369
     * 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
370
    void setZIndex(int zIndex);
Thomas Zander's avatar
Thomas Zander committed
371 372 373

    /**
     * Changes the Shape to be visible or invisible.
374
     * Being visible means being painted, as well as being used for
Thomas Zander's avatar
Thomas Zander committed
375 376
     *   things like guidelines or searches.
     * @param on when true; set the shape to be visible.
377
     * @see setGeometryProtected(), setContentProtected(), setSelectable()
Thomas Zander's avatar
Thomas Zander committed
378
     */
Thomas Zander's avatar
Thomas Zander committed
379
    void setVisible(bool on);
Thomas Zander's avatar
Thomas Zander committed
380 381
    /**
     * Returns current visibility state of this shape.
382
     * Being visible means being painted, as well as being used for
Thomas Zander's avatar
Thomas Zander committed
383
     *   things like guidelines or searches.
384
     * @param recursive when true, checks visibility recursively
Thomas Zander's avatar
Thomas Zander committed
385
     * @return current visibility state of this shape.
386
     * @see isGeometryProtected(), isContentProtected(), isSelectable()
Thomas Zander's avatar
Thomas Zander committed
387
     */
388
    bool isVisible(bool recursive = false) const;
Thomas Zander's avatar
Thomas Zander committed
389

390 391 392 393 394
    /**
     * 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),
395
     * it isPrinted will return false, too.
396 397 398 399 400 401 402 403 404 405 406 407
     */
    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;
408

409 410 411
    /**
     * Makes it possible for the user to select this shape.
     * This parameter defaults to true.
Thomas Zander's avatar
Thomas Zander committed
412
     * @param selectable when true; set the shape to be selectable by the user.
413
     * @see setGeometryProtected(), setContentProtected(), setVisible()
414
     */
Thomas Zander's avatar
Thomas Zander committed
415
    void setSelectable(bool selectable);
416
    /**
Thomas Zander's avatar
Thomas Zander committed
417
     * Returns if this shape can be selected by the user.
418
     * @return true only when the object is selectable.
419
     * @see isGeometryProtected(), isContentProtected(), isVisible()
420
     */
Thomas Zander's avatar
Thomas Zander committed
421
    bool isSelectable() const;
422

Thomas Zander's avatar
Thomas Zander committed
423
    /**
424 425 426 427 428
     * 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.
     * @see setContentProtected(), setSelectable(), setVisible()
Thomas Zander's avatar
Thomas Zander committed
429
     */
430
    void setGeometryProtected(bool on);
Thomas Zander's avatar
Thomas Zander committed
431
    /**
432 433 434 435 436
     * 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.
     * @see isContentProtected(), isSelectable(), isVisible()
Thomas Zander's avatar
Thomas Zander committed
437
     */
438
    bool isGeometryProtected() const;
Thomas Zander's avatar
Thomas Zander committed
439

440 441 442 443
    /**
     * 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.
444
     * @see setGeometryProtected(), setSelectable(), setVisible()
445 446 447 448 449 450
     */
    void setContentProtected(bool protect);
    /**
     * 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.
451
     * @see isGeometryProtected(), isSelectable(), isVisible()
452 453 454
     */
    bool isContentProtected() const;

Thomas Zander's avatar
Thomas Zander committed
455 456 457 458
    /**
     * 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
459
    KoShapeContainer *parent() const;
Thomas Zander's avatar
Thomas Zander committed
460 461 462 463 464 465 466 467 468 469 470 471 472 473

    /**
     * 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.
     */
474
    virtual void update() const;
Thomas Zander's avatar
Thomas Zander committed
475 476 477 478 479 480 481 482 483 484

    /**
     * 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.
     * @param shape the rectangle (in pt) to queue for repaint.
     */
485
    void update(const QRectF &shape) const;
Thomas Zander's avatar
Thomas Zander committed
486 487 488

    /**
     * This is a method used to sort a list using the STL sorting methods.
489 490
     * @param s1 the first shape
     * @param s2 the second shape
Thomas Zander's avatar
Thomas Zander committed
491
     */
492
    static bool compareShapeZIndex(KoShape *s1, KoShape *s2);
Thomas Zander's avatar
Thomas Zander committed
493 494 495 496 497 498 499 500 501 502 503 504 505 506

    /**
     * returns the outline of the shape in the form of a path.
     * The outline returned will always have the position() of the shape as the origin, so
     * moving the shape will not alter the result.  The outline is used to draw the border
     * on, for example.
     * @returns the outline of the shape in the form of a path.
     */
    virtual const QPainterPath outline() const;

    /**
     * Returns the currently set border, or 0 if there is no border.
     * @return the currently set border, or 0 if there is no border.
     */
507
    KoShapeBorderModel *border() const;
Thomas Zander's avatar
Thomas Zander committed
508 509 510 511 512

    /**
     * Set a new border, removing the old one.
     * @param border the new border, or 0 if there should be no border.
     */
513
    void setBorder(KoShapeBorderModel *border);
Thomas Zander's avatar
Thomas Zander committed
514

515 516 517 518 519 520
    /**
     * Return the insets of the border.
     * Convenience method for KoShapeBorderModel::borderInsets()
     */
    KoInsets borderInsets() const;

521
    /// Sets the new shadow, removing the old one
522
    void setShadow(KoShapeShadow * shadow);
523 524 525 526

    /// Returns the currently set shadow or 0 if there is now shadow set
    KoShapeShadow * shadow() const;

Thomas Zander's avatar
Thomas Zander committed
527 528 529 530 531 532
    /**
     * 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
533
    void setKeepAspectRatio(bool keepAspect);
534

Thomas Zander's avatar
Thomas Zander committed
535 536 537 538 539 540
    /**
     * 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
541
    bool keepAspectRatio() const;
Thomas Zander's avatar
Thomas Zander committed
542 543 544 545

    /**
     * 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>
546
     * @param anchor The place on the (unaltered) shape that you want the position of.
Thomas Zander's avatar
Thomas Zander committed
547 548
     * @return the point that is the absolute, centered position of this shape.
     */
Jan Hambrecht's avatar
Jan Hambrecht committed
549
    QPointF absolutePosition(KoFlake::Position anchor = KoFlake::CenteredPosition) const;
550

Thomas Zander's avatar
Thomas Zander committed
551 552 553 554 555 556 557 558 559 560 561 562
    /**
     * 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
563
     * @param anchor The place on the (unaltered) shape that you set the position of.
Thomas Zander's avatar
Thomas Zander committed
564
     */
Jan Hambrecht's avatar
Jan Hambrecht committed
565
    void setAbsolutePosition(QPointF newPosition, KoFlake::Position anchor = KoFlake::CenteredPosition);
Thomas Zander's avatar
Thomas Zander committed
566

567 568
    /**
     * Set a data object on the shape to be used by an application.
569
     * This is specifically useful when a shape is created in a plugin and that data from that
570 571 572 573 574 575 576 577 578
     * 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;

579 580 581 582 583 584 585 586 587 588 589 590
    /**
     * 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);
    /**
     * Return the current applicationData.
     */
    KoShapeApplicationData *applicationData() const;

591
    /**
Marijn Kruisselbrink's avatar
Marijn Kruisselbrink committed
592
     * Return the Id of this shape, identifying the type of shape by the id of the factory.
593 594 595
     * @see KoShapeFactory::shapeId()
     * @return the id of the shape-type
     */
Thomas Zander's avatar
Thomas Zander committed
596
    const QString & shapeId() const;
597 598 599 600 601 602
    /**
     * 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.
     * @see KoShapeFactory::shapeId()
     * @param id the ID from the factory that created this shape
     */
Thomas Zander's avatar
Thomas Zander committed
603
    void setShapeId(const QString &id);
604

Thomas Zander's avatar
Thomas Zander committed
605 606
    /**
     * Create a matrix that describes all the transformations done on this shape.
607 608 609 610
     *
     * The absolute transformation is the combined transformation of this shape
     * and all its parents and grandparents.
     *
Thomas Zander's avatar
Thomas Zander committed
611 612 613
     * @param converter if not null, this method uses the converter to mark the right
     *        offsets in the current view.
     */
614
    QMatrix absoluteTransformation(const KoViewConverter *converter) const;
Thomas Zander's avatar
Thomas Zander committed
615

616 617 618 619
    /**
     * Applies a transformation to this shape.
     *
     * The transformation given is relative to the global coordinate system, i.e. the document.
620 621
     * This is a convenience function to apply a global transformation to this shape.
     * @see applyTransformation
622 623 624
     *
     * @param matrix the transformation matrix to apply
     */
625
    void applyAbsoluteTransformation(const QMatrix &matrix);
626 627 628 629 630

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

633
    /// Returns the shapes local transformation matrix
634 635 636 637 638 639 640 641 642
    QMatrix transformation() const;

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

Thomas Zander's avatar
Thomas Zander committed
645 646 647 648 649 650 651 652
    /**
     * 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
     */
    virtual void copySettings(const KoShape *shape);

Thomas Zander's avatar
Thomas Zander committed
653 654 655 656 657 658 659 660 661
    /**
     * 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);

662 663 664 665 666
    /**
     * @brief Transforms point from shape coordinates to document coordinates
     * @param point in shape coordinates
     * @return point in document coordinates
     */
667
    QPointF shapeToDocument(const QPointF &point) const;
668 669 670 671 672 673

    /**
     * @brief Transforms rect from shape coordinates to document coordinates
     * @param rect in shape coordinates
     * @return rect in document coordinates
     */
674
    QRectF shapeToDocument(const QRectF &rect) const;
675 676 677 678 679 680

    /**
     * @brief Transforms point from document coordinates to shape coordinates
     * @param point in document coordinates
     * @return point in shape coordinates
     */
681
    QPointF documentToShape(const QPointF &point) const;
682 683 684 685 686 687

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

690 691 692 693
    /**
     * Returns the name of the shape.
     * @return the shapes name
     */
694
    QString name() const;
695 696 697 698 699

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

702 703 704 705 706
    /**
     * Update the position of the shape in the tree of the KoShapeManager.
     */
    void notifyChanged();

707
    /**
Thomas Zander's avatar
Thomas Zander committed
708 709
     * A shape can be in a state that it is doing processing data like loading or text layout.
     * In which case
710
     * it can be shown on screen just fine (probably partially) but it should really not be printed
Thomas Zander's avatar
Thomas Zander committed
711
     * until it is fully done processing.
712 713 714 715 716
     * Flake will call this method from a non-main thread and only start printing it when the
     * method returned.
     * Warning!  This method can be blocking for a long time, never call it on the gui-thread!
     */
    virtual void waitUntilReady() const {}
717

Thomas Zander's avatar
api dox  
Thomas Zander committed
718 719 720
    /**
     * 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
721 722 723 724
     * 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
725
     * thread will use it after its been removed, while painting for example.
Thomas Zander's avatar
Thomas Zander committed
726 727
     *
     * 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
728
     */
729
    void deleteLater();
730

731 732 733
    /// checks recursively if the shape or one of its parents is not visible or locked
    bool isEditable() const;

734 735
    /// Removes connection point with given index
    void removeConnectionPoint(int index);
736

737 738 739 740 741 742 743 744 745 746
    /**
     * Adds a shape which depends on this shape.
     *
     * 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
     * @return true if dependency could be established, else false
     */
    bool addDependee(KoShape * shape);
747 748

    /// Removes as shape depending on this shape
749
    void removeDependee(KoShape * shape);
750

751 752
    /// Returns if the given shape is dependent on this shape
    bool hasDependee(KoShape * shape) const;
753

754 755 756
    /// Returns additional snap data the shape wants to have snapping to
    virtual KoSnapData snapData() const;

757 758 759 760 761 762 763 764 765
    /**
     * 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
     */
766
    void setAdditionalAttribute(const char * name, const QString & value);
767 768 769 770 771 772

    /**
     * Remove additional attribute
     *
     * @param name The name of the attribute in the following form prefix:tag e.g. presentation:placeholder
     */
773
    void removeAdditionalAttribute(const char * name);
774 775 776 777 778 779 780 781

    /**
     * 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
     */
Thomas Zander's avatar
Thomas Zander committed
782
    bool hasAdditionalAttribute(const char * name) const;
783 784 785 786 787 788 789 790

    /**
     * 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.
     */
Thomas Zander's avatar
Thomas Zander committed
791
    QString additionalAttribute(const char * name) const;
792

793 794 795 796
    void setAdditionalStyleAttribute(const char * name, const QString & value);

    void removeAdditionalStyleAttribute(const char * name);

797 798 799 800 801
    /**
     * The first filter of the list is the first to be applied.
     *
     * @return the list of filter effects applied on the shape when rendering.
     */
Jan Hambrecht's avatar
Jan Hambrecht committed
802
    QList<KoFilterEffect*> filterEffectStack() const;
803 804 805 806 807 808
    
    /**
     * Inserts a new filter at the given position in the filter list.
     * @param index the list index to insert the new filter at
     * @param filter the new filter to insert
     */
Jan Hambrecht's avatar
Jan Hambrecht committed
809
    void insertFilterEffect(int index, KoFilterEffect * filter);
810 811 812 813 814
    
    /**
     * Removes the filter with the given index from the filter list.
     * @param index the index of the filter to remove
     */
Jan Hambrecht's avatar
Jan Hambrecht committed
815
    void removeFilterEffect(int index);
816

817
protected:
818 819
    /// constructor
    KoShape(KoShapePrivate &);
820

821
    /* ** loading saving helper methods */
822 823
    /// attributes from ODF 1.1 chapter 9.2.15 Common Drawing Shape Attributes
    enum OdfAttribute {
824 825
        OdfTransformation = 1,       ///< Store transformation information
        OdfSize = 2,                 ///< Store size information
826 827 828 829 830 831 832 833
        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
        OdfZIndex = 1024,            ///< This only loads the z-index; when saving, it is reflected by the order of the shapes.
834
        OdfViewbox = 2048,           ///< Store the viewbox
835 836 837 838 839

        /// A mask for all mandatory attributes
        OdfMandatories = OdfLayer | OdfStyle | OdfId | OdfName | OdfZIndex,
        /// A mask for geometry attributes
        OdfGeometry = OdfPosition | OdfSize,
840
        /// A mask for all the attributes
841
        OdfAllAttributes = OdfTransformation | OdfGeometry | OdfAdditionalAttributes | OdfMandatories | OdfCommonChildElements
842
    };
843

844 845 846 847 848 849 850
    /**
     * 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.
     */
851
    bool loadOdfAttributes(const KoXmlElement & element, KoShapeLoadingContext &context, int attributes);
852

Jan Hambrecht's avatar
 
Jan Hambrecht committed
853 854 855 856 857
    /**
     * Parses the transformation attribute from the given string
     * @param transform the transform attribute string
     * @return the resulting transformation matrix
     */
858
    QMatrix parseOdfTransform(const QString &transform);
Jan Hambrecht's avatar
 
Jan Hambrecht committed
859

860
    /**
861
     * @brief Saves the style used for the shape
862
     *
863 864
     * This method fills the given style object with the border and
     * background properties and then adds the style to the context.
865
     *
866
     * @param style the style object to fill
867 868 869
     * @param context used for saving
     * @return the name of the style
     * @see saveOdf
870
     */
871
    virtual QString saveStyle(KoGenStyle &style, KoShapeSavingContext &context) const;
872 873 874 875 876 877 878

    /**
     * Loads the stroke and fill style from the given element.
     *
     * @param element the xml element to  load the style from
     * @param context the loading context used for loading
     */
879
    virtual void loadStyle(const KoXmlElement & element, KoShapeLoadingContext &context);
880

881
    /// Loads the fill style
882
    //QBrush loadOdfFill( const KoXmlElement & element, KoShapeLoadingContext & context );
883
    KoShapeBackground * loadOdfFill(const KoXmlElement & element, KoShapeLoadingContext & context);
884

885
    /// Loads the stroke style
886
    KoShapeBorderModel * loadOdfStroke(const KoXmlElement & element, KoShapeLoadingContext & context);
887

888
    /// Loads the shadow style
889
    KoShapeShadow * loadOdfShadow(const KoXmlElement & element, KoShapeLoadingContext & context);
890

891 892 893
    /**
     * Fills the style stack and returns the value of the given style property (e.g fill, stroke).
     */
894
    QString getStyleProperty(const char *property, const KoXmlElement & element, KoShapeLoadingContext & context);
895

896
    /* ** end loading saving */
897

898

899 900 901 902 903
    /**
     * A hook that allows inheriting classes to do something after a KoShape property changed
     * This is called whenever the shape, position rotation or scale properties were altered.
     * @param type an indicator which type was changed.
     */
904
    virtual void shapeChanged(ChangeType type, KoShape *shape = 0);
905

Thomas Zander's avatar
Thomas Zander committed
906 907 908 909 910 911
    /**
     * 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.
     */
Thomas Zander's avatar
Thomas Zander committed
912
    void setCollisionDetection(bool detect);
913

Thomas Zander's avatar
Thomas Zander committed
914 915 916 917
    /**
     * get the property collision detection.
     * @returns true if collision detection is on.
     */
Thomas Zander's avatar
Thomas Zander committed
918
    bool collisionDetection();
Thomas Zander's avatar
Thomas Zander committed
919

Thomas Zander's avatar
Thomas Zander committed
920
    /// return the current matrix that contains the rotation/scale/position of this shape
921 922
    const QMatrix& matrix() const;

923 924
    KoShapePrivate *d_ptr;

Thomas Zander's avatar
Thomas Zander committed
925 926
private:
    friend class KoShapeManager;
927 928
    void addShapeManager(KoShapeManager * manager);
    void removeShapeManager(KoShapeManager * manager);
Thomas Zander's avatar
Thomas Zander committed
929

930
    Q_DECLARE_PRIVATE(KoShape)
Thomas Zander's avatar
Thomas Zander committed
931 932
};

933 934
Q_DECLARE_METATYPE(KoShape*)

Thomas Zander's avatar
Thomas Zander committed
935
#endif