juce/source/src/gui/graphics/drawables/juce_Drawable.h

   1 /*
   2   ==============================================================================
   3
   4    This file is part of the JUCE library - "Jules' Utility Class Extensions"
   5    Copyright 2004-11 by Raw Material Software Ltd.
   6
   7   ------------------------------------------------------------------------------
   8
   9    JUCE can be redistributed and/or modified under the terms of the GNU General
  10    Public License (Version 2), as published by the Free Software Foundation.
  11    A copy of the license is included in the JUCE distribution, or can be found
  12    online at www.gnu.org/licenses.
  13
  14    JUCE is distributed in the hope that it will be useful, but WITHOUT ANY
  15    WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
  16    A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
  17
  18   ------------------------------------------------------------------------------
  19
  20    To release a closed-source product which uses JUCE, commercial licenses are
  21    available: visit www.rawmaterialsoftware.com/juce for more information.
  22
  23   ==============================================================================
  24 */
  25
  26 #ifndef __JUCE_DRAWABLE_JUCEHEADER__
  27 #define __JUCE_DRAWABLE_JUCEHEADER__
  28
  29 #include "../../components/juce_Component.h"
  30 #include "../../components/positioning/juce_RelativeCoordinate.h"
  31 #include "../../components/positioning/juce_RelativeCoordinatePositioner.h"
  32 #include "../../../containers/juce_ValueTree.h"
  33 #include "../../components/layout/juce_ComponentBuilder.h"
  34 class DrawableComposite;
  35
  36
  37 //==============================================================================
  38 /**
  39     The base class for objects which can draw themselves, e.g. polygons, images, etc.
  40
  41     @see DrawableComposite, DrawableImage, DrawablePath, DrawableText
  42 */
  43 class JUCE_API  Drawable  : public Component
  44 {
  45 protected:
  46     //==============================================================================
  47     /** The base class can't be instantiated directly.
  48
  49         @see DrawableComposite, DrawableImage, DrawablePath, DrawableText
  50     */
  51     Drawable();
  52
  53 public:
  54     /** Destructor. */
  55     virtual ~Drawable();
  56
  57     //==============================================================================
  58     /** Creates a deep copy of this Drawable object.
  59
  60         Use this to create a new copy of this and any sub-objects in the tree.
  61     */
  62     virtual Drawable* createCopy() const = 0;
  63
  64     //==============================================================================
  65     /** Renders this Drawable object.
  66
  67         Note that the preferred way to render a drawable in future is by using it
  68         as a component and adding it to a parent, so you might want to consider that
  69         before using this method.
  70
  71         @see drawWithin
  72     */
  73     void draw (Graphics& g, float opacity,
  74                const AffineTransform& transform = AffineTransform::identity) const;
  75
  76     /** Renders the Drawable at a given offset within the Graphics context.
  77
  78         The co-ordinates passed-in are used to translate the object relative to its own
  79         origin before drawing it - this is basically a quick way of saying:
  80
  81         @code
  82         draw (g, AffineTransform::translation (x, y)).
  83         @endcode
  84
  85         Note that the preferred way to render a drawable in future is by using it
  86         as a component and adding it to a parent, so you might want to consider that
  87         before using this method.
  88     */
  89     void drawAt (Graphics& g, float x, float y, float opacity) const;
  90
  91     /** Renders the Drawable within a rectangle, scaling it to fit neatly inside without
  92         changing its aspect-ratio.
  93
  94         The object can placed arbitrarily within the rectangle based on a Justification type,
  95         and can either be made as big as possible, or just reduced to fit.
  96
  97         Note that the preferred way to render a drawable in future is by using it
  98         as a component and adding it to a parent, so you might want to consider that
  99         before using this method.
 100
 101         @param g                        the graphics context to render onto
 102         @param destArea                 the target rectangle to fit the drawable into
 103         @param placement                defines the alignment and rescaling to use to fit
 104                                         this object within the target rectangle.
 105         @param opacity                  the opacity to use, in the range 0 to 1.0
 106     */
 107     void drawWithin (Graphics& g,
 108                      const Rectangle<float>& destArea,
 109                      const RectanglePlacement& placement,
 110                      float opacity) const;
 111
 112
 113     //==============================================================================
 114     /** Resets any transformations on this drawable, and positions its origin within
 115         its parent component.
 116     */
 117     void setOriginWithOriginalSize (const Point<float>& originWithinParent);
 118
 119     /** Sets a transform for this drawable that will position it within the specified
 120         area of its parent component.
 121     */
 122     void setTransformToFit (const Rectangle<float>& areaInParent, const RectanglePlacement& placement);
 123
 124     /** Returns the DrawableComposite that contains this object, if there is one. */
 125     DrawableComposite* getParent() const;
 126
 127     //==============================================================================
 128     /** Tries to turn some kind of image file into a drawable.
 129
 130         The data could be an image that the ImageFileFormat class understands, or it
 131         could be SVG.
 132     */
 133     static Drawable* createFromImageData (const void* data, size_t numBytes);
 134
 135     /** Tries to turn a stream containing some kind of image data into a drawable.
 136
 137         The data could be an image that the ImageFileFormat class understands, or it
 138         could be SVG.
 139     */
 140     static Drawable* createFromImageDataStream (InputStream& dataSource);
 141
 142     /** Tries to turn a file containing some kind of image data into a drawable.
 143
 144         The data could be an image that the ImageFileFormat class understands, or it
 145         could be SVG.
 146     */
 147     static Drawable* createFromImageFile (const File& file);
 148
 149     /** Attempts to parse an SVG (Scalable Vector Graphics) document, and to turn this
 150         into a Drawable tree.
 151
 152         The object returned must be deleted by the caller. If something goes wrong
 153         while parsing, it may return 0.
 154
 155         SVG is a pretty large and complex spec, and this doesn't aim to be a full
 156         implementation, but it can return the basic vector objects.
 157     */
 158     static Drawable* createFromSVG (const XmlElement& svgDocument);
 159
 160     //==============================================================================
 161     /** Tries to create a Drawable from a previously-saved ValueTree.
 162         The ValueTree must have been created by the createValueTree() method.
 163         If there are any images used within the drawable, you'll need to provide a valid
 164         ImageProvider object that can be used to retrieve these images from whatever type
 165         of identifier is used to represent them.
 166         Internally, this uses a ComponentBuilder, and registerDrawableTypeHandlers().
 167     */
 168     static Drawable* createFromValueTree (const ValueTree& tree, ComponentBuilder::ImageProvider* imageProvider);
 169
 170     /** Creates a ValueTree to represent this Drawable.
 171         The ValueTree that is returned can be turned back into a Drawable with createFromValueTree().
 172         If there are any images used in this drawable, you'll need to provide a valid ImageProvider
 173         object that can be used to create storable representations of them.
 174     */
 175     virtual ValueTree createValueTree (ComponentBuilder::ImageProvider* imageProvider) const = 0;
 176
 177     /** Returns the area that this drawble covers.
 178         The result is expressed in this drawable's own coordinate space, and does not take
 179         into account any transforms that may be applied to the component.
 180     */
 181     virtual Rectangle<float> getDrawableBounds() const = 0;
 182
 183     //==============================================================================
 184     /** Internal class used to manage ValueTrees that represent Drawables. */
 185     class ValueTreeWrapperBase
 186     {
 187     public:
 188         ValueTreeWrapperBase (const ValueTree& state);
 189
 190         ValueTree& getState() noexcept          { return state; }
 191
 192         String getID() const;
 193         void setID (const String& newID);
 194
 195         ValueTree state;
 196     };
 197
 198     //==============================================================================
 199     /** Registers a set of ComponentBuilder::TypeHandler objects that can be used to
 200         load all the different Drawable types from a saved state.
 201         @see ComponentBuilder::registerTypeHandler()
 202     */
 203     static void registerDrawableTypeHandlers (ComponentBuilder& componentBuilder);
 204
 205 protected:
 206     //==============================================================================
 207     friend class DrawableComposite;
 208     friend class DrawableShape;
 209
 210     /** @internal */
 211     void transformContextToCorrectOrigin (Graphics& g);
 212     /** @internal */
 213     void parentHierarchyChanged();
 214     /** @internal */
 215     void setBoundsToEnclose (const Rectangle<float>& area);
 216
 217     Point<int> originRelativeToComponent;
 218
 219   #ifndef DOXYGEN
 220     /** Internal utility class used by Drawables. */
 221     template <class DrawableType>
 222     class Positioner  : public RelativeCoordinatePositionerBase
 223     {
 224     public:
 225         Positioner (DrawableType& component_)
 226             : RelativeCoordinatePositionerBase (component_),
 227               owner (component_)
 228         {}
 229
 230         bool registerCoordinates()      { return owner.registerCoordinates (*this); }
 231         void applyToComponentBounds()
 232         {
 233             ComponentScope scope (getComponent());
 234             owner.recalculateCoordinates (&scope);
 235         }
 236
 237         void applyNewBounds (const Rectangle<int>&)
 238         {
 239             jassertfalse; // drawables can't be resized directly!
 240         }
 241
 242     private:
 243         DrawableType& owner;
 244
 245         JUCE_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR (Positioner);
 246     };
 247   #endif
 248
 249 private:
 250     void nonConstDraw (Graphics& g, float opacity, const AffineTransform& transform);
 251
 252     JUCE_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR (Drawable);
 253 };
 254
 255
 256 #endif   // __JUCE_DRAWABLE_JUCEHEADER__