KoShape.h 37.2 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 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

29
#include <QTransform>
Thomas Zander's avatar
Thomas Zander committed
30
#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 KoDataCenterBase;
58
class KoShapeShadow;
59
class KoEventAction;
60
class KoShapePrivate;
61
class KoFilterEffectStack;
62
class KoSnapData;
Thomas Zander's avatar
Thomas Zander committed
63 64

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

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

    /**
     * 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
162
     * @param canvas the canvas that requested this paint.  This can be used to retrieve canvas specific properties
163
     *      like selection and get a reference to the KoResourceManager.
Thomas Zander's avatar
Thomas Zander committed
164
     */
165
    virtual void paintDecorations(QPainter &painter, const KoViewConverter &converter, const KoCanvasBase *canvas);
Thomas Zander's avatar
Thomas Zander committed
166

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

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

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

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

Thomas Zander's avatar
Thomas Zander committed
202 203 204 205 206 207 208
    /**
     * @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
209
    void scale(qreal sx, qreal sy);
Thomas Zander's avatar
Thomas Zander committed
210 211

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

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

    /**
     * @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
234
    void shear(qreal sx, qreal sy);
Thomas Zander's avatar
Thomas Zander committed
235 236 237 238

    /**
     * @brief Resize the shape
     *
239
     * @param size the new size of the shape.  This is different from scaling as
Jan Hambrecht's avatar
Jan Hambrecht committed
240
     * scaling is a so called secondary operation which is comparable to zooming in
Thomas Zander's avatar
Thomas Zander committed
241 242 243 244
     * 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.
     */
245
    virtual void setSize(const QSizeF &size);
Thomas Zander's avatar
Thomas Zander committed
246 247 248 249

    /**
     * @brief Get the size of the shape in pt.
     *
Thorsten Zachmann's avatar
Thorsten Zachmann committed
250 251
     * The size is in shape coordinates.
     *
Inge Wallin's avatar
Inge Wallin committed
252
     * @return the size of the shape as set by setSize()
Thomas Zander's avatar
Thomas Zander committed
253
     */
Thomas Zander's avatar
Thomas Zander committed
254
    virtual QSizeF size() const;
Thomas Zander's avatar
Thomas Zander committed
255 256 257 258 259 260

    /**
     * @brief Set the position of the shape in pt
     *
     * @param position the new position of the shape
     */
261
    virtual void setPosition(const QPointF &position);
Thomas Zander's avatar
Thomas Zander committed
262 263 264 265 266 267

    /**
     * @brief Get the position of the shape in pt
     *
     * @return the position of the shape
     */
268
    QPointF position() const;
Thomas Zander's avatar
Thomas Zander committed
269 270 271 272 273 274

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

    /**
     * @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
     */
284
    virtual QRectF boundingRect() const;
Thomas Zander's avatar
Thomas Zander committed
285 286 287 288 289 290 291 292 293 294 295

    /**
     * @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.
     */
296
    void addConnectionPoint(const QPointF &point);
Thomas Zander's avatar
Thomas Zander committed
297

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

305
    /**
306
     * Add a event action
307
     */
308
    void addEventAction(KoEventAction *action);
309 310 311 312

    /**
     * Remove a event action
     */
313
    void removeEventAction(KoEventAction *action);
314 315 316 317

    /**
     * Get all event actions
     */
318
    QSet<KoEventAction *> eventActions() const;
319

Thomas Zander's avatar
Thomas Zander committed
320 321
    /**
     * Set the background of the shape.
322
     * A shape background can be a plain color, a gradient, a pattern, be fully transparent
Jan Hambrecht's avatar
Jan Hambrecht committed
323
     * or have a complex fill.
324
     * Setting such a background will allow the shape to be filled and will be able to tell
Jan Hambrecht's avatar
Jan Hambrecht committed
325 326
     * if it is transparent or not.
     * @param background the new shape background.
Thomas Zander's avatar
Thomas Zander committed
327
     */
328 329
    void setBackground(KoShapeBackground *background);

Thomas Zander's avatar
Thomas Zander committed
330 331
    /**
     * return the brush used to paint te background of this shape with.
332
     * A QBrush can have a plain color, be fully transparent or have a complex fill.
Thomas Zander's avatar
Thomas Zander committed
333
     * setting such a brush will allow the shape to fill itself using that brush and
334
     * will be able to tell if its transparent or not.
Thomas Zander's avatar
Thomas Zander committed
335 336
     * @return the background-brush
     */
337
    KoShapeBackground *background() const;
Thomas Zander's avatar
Thomas Zander committed
338 339

    /**
340 341
     * 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
342
     * you should override it and always return true if your shape is not square.
343
     * @return if the shape is (partly) transparent.
Thomas Zander's avatar
Thomas Zander committed
344
     */
Thomas Zander's avatar
Thomas Zander committed
345
    virtual bool hasTransparency() const;
Thomas Zander's avatar
Thomas Zander committed
346

347 348 349 350 351
    /**
     * Sets shape level transparency.
     * @param transparency the new shape level transparency
     */
    void setTransparency(qreal transparency);
352

353 354 355 356 357
    /**
     * Returns the shape level transparency.
     * @param recursive when true takes the parents transparency into account
     */
    qreal transparency(bool recursive=false) const;
358

Thomas Zander's avatar
Thomas Zander committed
359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374
    /**
     * 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.
375
     * The layering if two overlapping objects have the same index is implementation dependent
Thomas Zander's avatar
Thomas Zander committed
376 377 378
     * 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
379
    void setZIndex(int zIndex);
Thomas Zander's avatar
Thomas Zander committed
380 381 382

    /**
     * Changes the Shape to be visible or invisible.
383
     * Being visible means being painted, as well as being used for
Thomas Zander's avatar
Thomas Zander committed
384 385
     *   things like guidelines or searches.
     * @param on when true; set the shape to be visible.
386
     * @see setGeometryProtected(), setContentProtected(), setSelectable()
Thomas Zander's avatar
Thomas Zander committed
387
     */
Thomas Zander's avatar
Thomas Zander committed
388
    void setVisible(bool on);
Thomas Zander's avatar
Thomas Zander committed
389 390
    /**
     * Returns current visibility state of this shape.
391
     * Being visible means being painted, as well as being used for
Thomas Zander's avatar
Thomas Zander committed
392
     *   things like guidelines or searches.
393
     * @param recursive when true, checks visibility recursively
Thomas Zander's avatar
Thomas Zander committed
394
     * @return current visibility state of this shape.
395
     * @see isGeometryProtected(), isContentProtected(), isSelectable()
Thomas Zander's avatar
Thomas Zander committed
396
     */
397
    bool isVisible(bool recursive = false) const;
Thomas Zander's avatar
Thomas Zander committed
398

399 400 401 402 403
    /**
     * 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),
404
     * it isPrinted will return false, too.
405 406 407 408 409 410 411 412 413 414 415 416
     */
    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;
417

418 419 420
    /**
     * Makes it possible for the user to select this shape.
     * This parameter defaults to true.
Thomas Zander's avatar
Thomas Zander committed
421
     * @param selectable when true; set the shape to be selectable by the user.
422
     * @see setGeometryProtected(), setContentProtected(), setVisible(), setPositionProtected(), setSizetProtected()
423
     */
Thomas Zander's avatar
Thomas Zander committed
424
    void setSelectable(bool selectable);
425

426
    /**
Thomas Zander's avatar
Thomas Zander committed
427
     * Returns if this shape can be selected by the user.
428
     * @return true only when the object is selectable.
429
     * @see isGeometryProtected(), isContentProtected(), isVisible(), isPositionPretected(), isSizeProtected()
430
     */
Thomas Zander's avatar
Thomas Zander committed
431
    bool isSelectable() const;
432

Thomas Zander's avatar
Thomas Zander committed
433
    /**
434 435 436 437
     * 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.
438
     * @see setContentProtected(), setSelectable(), setVisible(), setPositionProtected(), setSizetProtected()
Thomas Zander's avatar
Thomas Zander committed
439
     */
440
    void setGeometryProtected(bool on);
441

Thomas Zander's avatar
Thomas Zander committed
442
    /**
443 444 445 446
     * 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.
447
     * @see isContentProtected(), isSelectable(), isVisible(), isPositionPretected(), isSizeProtected()
Thomas Zander's avatar
Thomas Zander committed
448
     */
449
    bool isGeometryProtected() const;
Thomas Zander's avatar
Thomas Zander committed
450

451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478
    /**
    * Tells the shape to have its size protected from user changes.
    * @param on when true; set the sape to have its size protected.
    * @see setGeometryProtected(), setSelectable(), setVisible(), setPositionProtected(), setContentProtected()
    */
    void setSizeProtected(bool on);

    /**
    * Returns current size protection state of this shape.
    * @return current size protection state of this shape.
    * @see isGeometryProtected(), isSelectable(), isVisible(), isPositionPretected(), isContentProtected()
    */
    bool isSizeProtected() const;

    /**
    * Tells the shape to have its position protected from user changes.
    * @param on when true; set the sape to have its size protected.
    * @see setGeometryProtected(), setSelectable(), setVisible(), setSizeProtected(), setContentProtected()
    */
    void setPositionProtected(bool on);

    /**
    * Returns current size protection state of this shape.
    * @return current size protection state of this shape.
    * @see isGeometryProtected(), isSelectable(), isVisible(), isSizePretected(), isContentProtected()
    */
    bool isPositionProtected() const;

479 480 481 482
    /**
     * 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.
483
     * @see setGeometryProtected(), setSelectable(), setVisible(), setSizeProtected(), setPositionProtected()
484 485
     */
    void setContentProtected(bool protect);
486

487 488 489 490
    /**
     * 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.
491
     * @see isGeometryProtected(), isSelectable(), isVisible(), isPositionPretected(), isSizeProtected()
492 493 494
     */
    bool isContentProtected() const;

Thomas Zander's avatar
Thomas Zander committed
495 496 497 498
    /**
     * 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
499
    KoShapeContainer *parent() const;
Thomas Zander's avatar
Thomas Zander committed
500 501 502 503 504 505 506 507 508 509 510 511 512 513

    /**
     * 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.
     */
514
    virtual void update() const;
Thomas Zander's avatar
Thomas Zander committed
515 516 517 518 519 520 521 522 523 524

    /**
     * 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.
     */
525
    virtual void update(const QRectF &shape) const;
Thomas Zander's avatar
Thomas Zander committed
526 527 528

    /**
     * This is a method used to sort a list using the STL sorting methods.
529 530
     * @param s1 the first shape
     * @param s2 the second shape
Thomas Zander's avatar
Thomas Zander committed
531
     */
532
    static bool compareShapeZIndex(KoShape *s1, KoShape *s2);
Thomas Zander's avatar
Thomas Zander committed
533 534 535 536 537 538 539 540

    /**
     * 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.
     */
541
    virtual QPainterPath outline() const;
Thomas Zander's avatar
Thomas Zander committed
542 543 544 545 546

    /**
     * Returns the currently set border, or 0 if there is no border.
     * @return the currently set border, or 0 if there is no border.
     */
547
    KoShapeBorderModel *border() const;
Thomas Zander's avatar
Thomas Zander committed
548 549 550 551 552

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

555 556 557 558 559 560
    /**
     * Return the insets of the border.
     * Convenience method for KoShapeBorderModel::borderInsets()
     */
    KoInsets borderInsets() const;

561
    /// Sets the new shadow, removing the old one
562
    void setShadow(KoShapeShadow *shadow);
563 564

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

Thomas Zander's avatar
Thomas Zander committed
567 568 569 570 571 572
    /**
     * 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
573
    void setKeepAspectRatio(bool keepAspect);
574

Thomas Zander's avatar
Thomas Zander committed
575 576 577 578 579 580
    /**
     * 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
581
    bool keepAspectRatio() const;
Thomas Zander's avatar
Thomas Zander committed
582 583 584 585

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

Thomas Zander's avatar
Thomas Zander committed
591 592 593 594 595 596 597 598 599 600 601 602
    /**
     * 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
603
     * @param anchor The place on the (unaltered) shape that you set the position of.
Thomas Zander's avatar
Thomas Zander committed
604
     */
Jan Hambrecht's avatar
Jan Hambrecht committed
605
    void setAbsolutePosition(QPointF newPosition, KoFlake::Position anchor = KoFlake::CenteredPosition);
Thomas Zander's avatar
Thomas Zander committed
606

607 608
    /**
     * Set a data object on the shape to be used by an application.
609
     * This is specifically useful when a shape is created in a plugin and that data from that
610 611 612 613 614 615 616 617 618
     * 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;

619 620 621 622 623 624 625
    /**
     * 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);
626

627 628 629 630 631
    /**
     * Return the current applicationData.
     */
    KoShapeApplicationData *applicationData() const;

632
    /**
Marijn Kruisselbrink's avatar
Marijn Kruisselbrink committed
633
     * Return the Id of this shape, identifying the type of shape by the id of the factory.
634
     * @see KoShapeFactoryBase::shapeId()
635 636
     * @return the id of the shape-type
     */
637 638
    QString shapeId() const;

639 640 641
    /**
     * 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.
642
     * @see KoShapeFactoryBase::shapeId()
643 644
     * @param id the ID from the factory that created this shape
     */
Thomas Zander's avatar
Thomas Zander committed
645
    void setShapeId(const QString &id);
646

Thomas Zander's avatar
Thomas Zander committed
647 648
    /**
     * Create a matrix that describes all the transformations done on this shape.
649 650 651 652
     *
     * The absolute transformation is the combined transformation of this shape
     * and all its parents and grandparents.
     *
Thomas Zander's avatar
Thomas Zander committed
653 654 655
     * @param converter if not null, this method uses the converter to mark the right
     *        offsets in the current view.
     */
656
    QTransform absoluteTransformation(const KoViewConverter *converter) const;
Thomas Zander's avatar
Thomas Zander committed
657

658 659 660 661
    /**
     * Applies a transformation to this shape.
     *
     * The transformation given is relative to the global coordinate system, i.e. the document.
662 663
     * This is a convenience function to apply a global transformation to this shape.
     * @see applyTransformation
664 665 666
     *
     * @param matrix the transformation matrix to apply
     */
667
    void applyAbsoluteTransformation(const QTransform &matrix);
668 669 670 671 672

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

675
    /// Returns the shapes local transformation matrix
676
    QTransform transformation() const;
677 678 679 680 681 682 683 684

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

Thomas Zander's avatar
Thomas Zander committed
687 688 689 690 691 692
    /**
     * 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
693
    void copySettings(const KoShape *shape);
Thomas Zander's avatar
Thomas Zander committed
694

Thomas Zander's avatar
Thomas Zander committed
695 696 697 698 699 700 701 702 703
    /**
     * 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);

704 705 706 707 708
    /**
     * @brief Transforms point from shape coordinates to document coordinates
     * @param point in shape coordinates
     * @return point in document coordinates
     */
709
    QPointF shapeToDocument(const QPointF &point) const;
710 711 712 713 714 715

    /**
     * @brief Transforms rect from shape coordinates to document coordinates
     * @param rect in shape coordinates
     * @return rect in document coordinates
     */
716
    QRectF shapeToDocument(const QRectF &rect) const;
717 718 719 720 721 722

    /**
     * @brief Transforms point from document coordinates to shape coordinates
     * @param point in document coordinates
     * @return point in shape coordinates
     */
723
    QPointF documentToShape(const QPointF &point) const;
724 725 726 727 728 729

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

732 733 734 735
    /**
     * Returns the name of the shape.
     * @return the shapes name
     */
736
    QString name() const;
737 738 739 740 741

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

744 745 746 747 748
    /**
     * Update the position of the shape in the tree of the KoShapeManager.
     */
    void notifyChanged();

749
    /**
Thomas Zander's avatar
Thomas Zander committed
750
     * A shape can be in a state that it is doing processing data like loading or text layout.
751
     * 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
752
     * until it is fully done processing.
753 754 755 756 757 758 759 760 761
     * Warning! This method can be blocking for a long time
     * @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 
     *                     start printing it when the in case of printing method returned.
     *                     If set to false the processing needs to be done synchronously and will 
     *                     block until the result is finished.
     */
    virtual void waitUntilReady(const KoViewConverter &converter, bool asynchronous = true) const;
762

Thomas Zander's avatar
api dox  
Thomas Zander committed
763 764 765
    /**
     * 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
766 767 768 769
     * 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
770
     * thread will use it after its been removed, while painting for example.
Thomas Zander's avatar
Thomas Zander committed
771 772
     *
     * 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
773
     */
774
    void deleteLater();
775

776 777 778
    /// checks recursively if the shape or one of its parents is not visible or locked
    bool isEditable() const;

779 780
    /// Removes connection point with given index
    void removeConnectionPoint(int index);
781

782 783
    /**
     * Adds a shape which depends on this shape.
784 785
     * Making a shape dependent on this one means it will get shapeChanged() called
     * on each update of this shape.
786 787 788 789 790
     *
     * 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
791 792
     * @return true if dependency could be established, otherwise false
     * @see removeDependee(), hasDependee()
793
     */
794
    bool addDependee(KoShape *shape);
795

796 797 798 799
    /**
     * Removes as shape depending on this shape.
     * @see addDependee(), hasDependee()
     */
800
    void removeDependee(KoShape *shape);
801

802
    /// Returns if the given shape is dependent on this shape
803
    bool hasDependee(KoShape *shape) const;
804

805 806 807
    /// Returns additional snap data the shape wants to have snapping to
    virtual KoSnapData snapData() const;

808 809 810 811 812 813 814 815 816
    /**
     * 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
     */
817
    void setAdditionalAttribute(const char *name, const QString &value);
818 819 820 821 822 823

    /**
     * Remove additional attribute
     *
     * @param name The name of the attribute in the following form prefix:tag e.g. presentation:placeholder
     */
824
    void removeAdditionalAttribute(const char *name);
825 826 827 828 829 830 831 832

    /**
     * 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
     */
833
    bool hasAdditionalAttribute(const char *name) const;
834 835 836 837 838 839 840 841

    /**
     * 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.
     */
842
    QString additionalAttribute(const char *name) const;
843

844
    void setAdditionalStyleAttribute(const char *name, const QString &value);
845

846
    void removeAdditionalStyleAttribute(const char *name);
847

848
    /**
849
     * Returns the filter effect stack of the shape
850 851 852
     *
     * @return the list of filter effects applied on the shape when rendering.
     */
853
    KoFilterEffectStack *filterEffectStack() const;
854

855
    /// Sets the new filter effect stack, removing the old one
856
    void setFilterEffectStack(KoFilterEffectStack *filterEffectStack);
857

858 859 860 861 862 863 864 865 866 867 868 869 870 871
    /**
     * 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();

872 873 874 875 876 877
    /**
     * 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
878
     * Notice that if the set is non-empty 'this' shape is no longer looked at. You can choose
879 880 881 882 883 884 885 886 887 888 889
     * 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);

890 891 892 893 894 895
    /**
     * \internal
     * Returns the private object for use withing the flake lib
     */
    KoShapePrivate *priv();

896
protected:
897 898
    /// constructor
    KoShape(KoShapePrivate &);
899

900
    /* ** loading saving helper methods */
901 902
    /// attributes from ODF 1.1 chapter 9.2.15 Common Drawing Shape Attributes
    enum OdfAttribute {
903 904
        OdfTransformation = 1,       ///< Store transformation information
        OdfSize = 2,                 ///< Store size information
905 906 907 908 909 910 911 912
        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.
913
        OdfViewbox = 2048,           ///< Store the viewbox
914 915 916 917 918

        /// A mask for all mandatory attributes
        OdfMandatories = OdfLayer | OdfStyle | OdfId | OdfName | OdfZIndex,
        /// A mask for geometry attributes
        OdfGeometry = OdfPosition | OdfSize,
919
        /// A mask for all the attributes
920
        OdfAllAttributes = OdfTransformation | OdfGeometry | OdfAdditionalAttributes | OdfMandatories | OdfCommonChildElements
921
    };
922

923 924 925 926 927 928 929
    /**
     * 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.
     */
930
    bool loadOdfAttributes(const KoXmlElement &element, KoShapeLoadingContext &context, int attributes);
931

Jan Hambrecht's avatar
 
Jan Hambrecht committed
932 933 934 935 936
    /**
     * Parses the transformation attribute from the given string
     * @param transform the transform attribute string
     * @return the resulting transformation matrix
     */
937
    QTransform parseOdfTransform(const QString &transform);
Jan Hambrecht's avatar
 
Jan Hambrecht committed
938

939
    /**
940
     * @brief Saves the style used for the shape
941
     *
942 943
     * This method fills the given style object with the border and
     * background properties and then adds the style to the context.
944
     *
945
     * @param style the style object to fill
946 947 948
     * @param context used for saving
     * @return the name of the style
     * @see saveOdf
949
     */
950
    virtual QString saveStyle(KoGenStyle &style, KoShapeSavingContext &context) const;
951 952 953 954 955 956 957

    /**
     * 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
     */
958
    virtual void loadStyle(const KoXmlElement &element, KoShapeLoadingContext &context);
959

960
    /// Loads the stroke style
961
    KoShapeBorderModel *loadOdfStroke(const KoXmlElement &element, KoShapeLoadingContext &context) const;
962

963
    /// Loads the shadow style
964
    KoShapeBackground *loadOdfFill(KoShapeLoadingContext &context) const;
965

966
    /* ** end loading saving */
967

968 969 970 971 972
    /**
     * 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.
     */
973
    virtual void shapeChanged(ChangeType type, KoShape *shape = 0);
974

Thomas Zander's avatar
Thomas Zander committed
975
    /// return the current matrix that contains the rotation/scale/position of this shape
976
    QTransform transform() const;
977

978 979
    KoShapePrivate *d_ptr;

Thomas Zander's avatar
Thomas Zander committed
980
private:
981
    Q_DECLARE_PRIVATE(KoShape)
Thomas Zander's avatar
Thomas Zander committed
982 983
};

984 985
Q_DECLARE_METATYPE(KoShape*)

Thomas Zander's avatar
Thomas Zander committed
986
#endif