KoShapeContainer.h 9.57 KB
Newer Older
Thomas Zander's avatar
Thomas Zander committed
1
/* This file is part of the KDE project
Thomas Zander's avatar
Thomas Zander committed
2
 * Copyright (C) 2006-2010 Thomas Zander <zander@kde.org>
Thomas Zander's avatar
Thomas Zander committed
3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19
 *
 * 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
20 21
#ifndef KOSHAPECONTAINER_H
#define KOSHAPECONTAINER_H
Thomas Zander's avatar
Thomas Zander committed
22 23 24 25 26

#include "KoShape.h"

#include <QList>

27
#include "kritaflake_export.h"
Thomas Zander's avatar
Thomas Zander committed
28

Thomas Zander's avatar
Thomas Zander committed
29
class QPainter;
30
class KoShapeContainerModel;
31
class KoShapeContainerPrivate;
32
class KoViewConverter;
Thomas Zander's avatar
Thomas Zander committed
33 34

/**
Thomas Zander's avatar
Thomas Zander committed
35 36 37
 * This is the base class that all Flake group-shapes are based on.
 * Extending from this class allows you to have child-shapes.
 * Like the KoShape class, this shape is a visible class with
Thomas Zander's avatar
Thomas Zander committed
38 39
 * a position and a size. It can paint itself as well if you implement
 * the paintComponent() method.
40
 *
Thomas Zander's avatar
Thomas Zander committed
41 42
 * <p>The most important feature of this class is that you can make
 * other KoShape classes to be children of this container.
43
 *
Thomas Zander's avatar
Thomas Zander committed
44
 * <p>The effect of grouping those shapes is that their position
Thomas Zander's avatar
Thomas Zander committed
45 46
 * is relative to the position of the container. Move the container and
 * all children move with it.
47
 *
Thomas Zander's avatar
Thomas Zander committed
48
 * <p>Each child can optionally be said to be 'clipped' by the container.
49
 * This feature will give the effect that if the child has a size and
50
 * position outside the container, parts outside the container will not be shown.
51
 * This is especially useful
Thomas Zander's avatar
Thomas Zander committed
52
 * for showing cutouts of content, like images, without changing the actual content.
53
 *
Thomas Zander's avatar
Thomas Zander committed
54
 * <p>For so called clipped children any modification made to the container is
55 56 57
 * propagated to the child. This includes rotation as well as scaling
 * and shearing.
 *
Thomas Zander's avatar
Thomas Zander committed
58 59
 * <p>Maintaining the list of children can be done using the supplied methods
 * addChild() and removeChild(). However, they only forward their requests to the
60
 * data model KoShapeContainerModel and if you provide a custom implementation
Thomas Zander's avatar
Thomas Zander committed
61
 * of that model any means can be used to maintain a list of children, as long as
Thomas Zander's avatar
Thomas Zander committed
62
 * you will take care to register them with the appropriate shape manager.
63
 *
64
 * <p>An example usage where a custom model might be useful is when you have a
Thomas Zander's avatar
Thomas Zander committed
65 66 67 68
 * container for text areas which are split into columns.  If you resize the container
 * and the width of the individual columns gets too small, the model can choose to
 * remove a child or add one when the width allows another column.
 */
69
class KRITAFLAKE_EXPORT KoShapeContainer : public KoShape
70
{
Thomas Zander's avatar
Thomas Zander committed
71
public:
72

Thomas Zander's avatar
Thomas Zander committed
73 74
    /**
     * Constructor with custom model to be used for maintaining the list of children.
75 76 77
     * For all the normal cases you don't need a custom model. Only when you want to respond
     * to moves of the container to do something special, or disable one of the features the
     * container normally has (like clipping).  Use the default constructor in those cases.
Thomas Zander's avatar
Thomas Zander committed
78 79
     * @param model the custom model to be used for maintaining the list of children.
     */
80
    explicit KoShapeContainer(KoShapeContainerModel *model = 0);
Thomas Zander's avatar
Thomas Zander committed
81

Thomas Zander's avatar
Thomas Zander committed
82 83 84 85
    /**
     * Destructor for the shape container.
     * All children will be orphaned by calling a KoShape::setParent(0)
     */
Thomas Zander's avatar
Thomas Zander committed
86 87 88 89
    virtual ~KoShapeContainer();

    /**
     * Add a child to this container.
90 91 92 93
     *
     * This container will NOT take over ownership of the shape. The caller or those creating
     * the shape is responsible to delete it if not needed any longer.
     *
Thomas Zander's avatar
Thomas Zander committed
94
     * @param shape the child to be managed in the container.
Thomas Zander's avatar
Thomas Zander committed
95
     */
Thomas Zander's avatar
Thomas Zander committed
96
    void addShape(KoShape *shape);
Thomas Zander's avatar
Thomas Zander committed
97 98 99

    /**
     * Remove a child to be completely separated from the container.
100 101 102
     *
     * The shape will only be removed from this container but not be deleted.
     *
Thomas Zander's avatar
Thomas Zander committed
103
     * @param shape the child to be removed.
Thomas Zander's avatar
Thomas Zander committed
104
     */
Thomas Zander's avatar
Thomas Zander committed
105
    void removeShape(KoShape *shape);
Thomas Zander's avatar
Thomas Zander committed
106 107

    /**
108 109
     * Return the current number of children registered.
     * @return the current number of children registered.
Thomas Zander's avatar
Thomas Zander committed
110
     */
Thomas Zander's avatar
Thomas Zander committed
111
    int shapeCount() const;
Thomas Zander's avatar
Thomas Zander committed
112 113 114

    /**
     * Set the argument child to have its 'clipping' property set.
Thomas Zander's avatar
Thomas Zander committed
115 116 117 118 119 120 121
     *
     * A shape that is clipped by the container will have its visible portion
     * limited to the area where it intersects with the container.
     * If a shape is positioned or sized such that it would be painted outside
     * of the KoShape::outline() of its parent container, setting this property
     * to true will clip the shape painting to the container outline.
     *
Thomas Zander's avatar
Thomas Zander committed
122 123 124
     * @param child the child for which the property will be changed.
     * @param clipping the property
     */
Thomas Zander's avatar
Thomas Zander committed
125
    void setClipped(const KoShape *child, bool clipping);
Thomas Zander's avatar
Thomas Zander committed
126 127 128

    /**
     * Returns if the argument child has its 'clipping' property set.
Thomas Zander's avatar
Thomas Zander committed
129 130 131 132 133 134 135
     *
     * A shape that is clipped by the container will have its visible portion
     * limited to the area where it intersects with the container.
     * If a shape is positioned or sized such that it would be painted outside
     * of the KoShape::outline() of its parent container, setting this property
     * to true will clip the shape painting to the container outline.
     *
Thomas Zander's avatar
Thomas Zander committed
136 137 138
     * @return if the argument child has its 'clipping' property set.
     * @param child the child for which the property will be returned.
     */
Thomas Zander's avatar
Thomas Zander committed
139
    bool isClipped(const KoShape *child) const;
Thomas Zander's avatar
Thomas Zander committed
140

141
    /**
Halla Rempt's avatar
Halla Rempt committed
142
     * Return whether the child has the effective state of being locked for user modifications.
143
     * This method is deferred to the model, which should call the KoShape::isGeometryProtected() on the child.
144 145 146 147
     * @param child the shape that the user wants to move.
     */
    bool isChildLocked(const KoShape *child) const;

148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177

    /**
     * Set the shape to inherit the container transform.
     *
     * A shape that inherits the transform of the parent container will have its
     * share / rotation / skew etc be calculated as being the product of both its
     * own local transformation and also that of its parent container.
     * If you set this to true and rotate the container, the shape will get that
     * rotation as well automatically.
     *
     * @param shape the shape for which the property will be changed.
     * @param inherit the new value
     */
    void setInheritsTransform(const KoShape *shape, bool inherit);

    /**
     * Returns if the shape inherits the container transform.
     *
     * A shape that inherits the transform of the parent container will have its
     * share / rotation / skew etc be calculated as being the product of both its
     * own local transformation and also that of its parent container.
     * If you set this to true and rotate the container, the shape will get that
     * rotation as well automatically.
     *
     * @return if the argument shape has its 'inherits transform' property set.
     * @param shape the shape for which the property will be returned.
     */
    bool inheritsTransform(const KoShape *shape) const;


178
    /// reimplemented
179
    virtual void paint(QPainter &painter, const KoViewConverter &converter, KoShapePaintingContext &paintcontext);
Thomas Zander's avatar
Thomas Zander committed
180 181 182

    /**
     * @brief Paint the component
Thomas Zander's avatar
Thomas Zander committed
183
     * Implement this method to allow the shape to paint itself, just like the KoShape::paint()
Thomas Zander's avatar
Thomas Zander committed
184 185
     * method does.
     *
Thomas Zander's avatar
Thomas Zander committed
186
     * @param painter used for painting the shape
Thomas Zander's avatar
Thomas Zander committed
187 188 189
     * @param converter to convert between internal and view coordinates.
     * @see applyConversion()
     */
190
    virtual void paintComponent(QPainter &painter, const KoViewConverter &converter, KoShapePaintingContext &paintcontext) = 0;
Thomas Zander's avatar
Thomas Zander committed
191

192
    using KoShape::update;
193
    /// reimplemented
194
    virtual void update() const;
Thomas Zander's avatar
Thomas Zander committed
195 196

    /**
Thorsten Zachmann's avatar
Thorsten Zachmann committed
197 198
     * Return the list of all child shapes.
     * @return the list of all child shapes
Thomas Zander's avatar
Thomas Zander committed
199
     */
Thomas Zander's avatar
Thomas Zander committed
200
    QList<KoShape*> shapes() const;
Thomas Zander's avatar
Thomas Zander committed
201

Thomas Zander's avatar
Thomas Zander committed
202 203 204 205 206
    /**
     * return the model for this container
     */
    KoShapeContainerModel *model() const;

207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240

    /**
     * A special interface for KoShape to use during setParent call. Don't use
     * these method directly for managing shapes hierarchy! Use shape->setParent()
     * instead.
     */
    struct ShapeInterface {
        ShapeInterface(KoShapeContainer *_q);

        /**
         * Add a child to this container.
         *
         * This container will NOT take over ownership of the shape. The caller or those creating
         * the shape is responsible to delete it if not needed any longer.
         *
         * @param shape the child to be managed in the container.
         */
        void addShape(KoShape *shape);

        /**
         * Remove a child to be completely separated from the container.
         *
         * The shape will only be removed from this container but not be deleted.
         *
         * @param shape the child to be removed.
         */
        void removeShape(KoShape *shape);

    protected:
        KoShapeContainer *q;
    };

    ShapeInterface* shapeInterface();

241
protected:
Thomas Zander's avatar
Thomas Zander committed
242 243 244 245 246 247
    /**
     * This hook is for inheriting classes that need to do something on adding/removing
     * of children.
     * This method will be called just after the child has been added/removed.
     * The default implementation is empty.
     */
Thomas Zander's avatar
Thomas Zander committed
248
    virtual void shapeCountChanged() { }
249

Thorsten Zachmann's avatar
Thorsten Zachmann committed
250 251
    virtual void shapeChanged(ChangeType type, KoShape *shape = 0);

252
    /// constructor
253
    KoShapeContainer(KoShapeContainerPrivate *);
254

Thomas Zander's avatar
Thomas Zander committed
255
private:
256
    Q_DECLARE_PRIVATE(KoShapeContainer)
Thomas Zander's avatar
Thomas Zander committed
257 258 259
};

#endif