juce/source/src/gui/components/windows/juce_ResizableWindow.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_RESIZABLEWINDOW_JUCEHEADER__
  27 #define __JUCE_RESIZABLEWINDOW_JUCEHEADER__
  28
  29 #include "juce_TopLevelWindow.h"
  30 #include "../mouse/juce_ComponentDragger.h"
  31 #include "../layout/juce_ResizableBorderComponent.h"
  32 #include "../layout/juce_ResizableCornerComponent.h"
  33
  34
  35 //==============================================================================
  36 /**
  37     A base class for top-level windows that can be dragged around and resized.
  38
  39     To add content to the window, use its setContentOwned() or setContentNonOwned() methods
  40     to give it a component that will remain positioned inside it (leaving a gap around
  41     the edges for a border).
  42
  43     It's not advisable to add child components directly to a ResizableWindow: put them
  44     inside your content component instead. And overriding methods like resized(), moved(), etc
  45     is also not recommended - instead override these methods for your content component.
  46     (If for some obscure reason you do need to override these methods, always remember to
  47     call the super-class's resized() method too, otherwise it'll fail to lay out the window
  48     decorations correctly).
  49
  50     By default resizing isn't enabled - use the setResizable() method to enable it and
  51     to choose the style of resizing to use.
  52
  53     @see TopLevelWindow
  54 */
  55 class JUCE_API  ResizableWindow  : public TopLevelWindow
  56 {
  57 public:
  58     //==============================================================================
  59     /** Creates a ResizableWindow.
  60
  61         This constructor doesn't specify a background colour, so the LookAndFeel's default
  62         background colour will be used.
  63
  64         @param name                 the name to give the component
  65         @param addToDesktop         if true, the window will be automatically added to the
  66                                     desktop; if false, you can use it as a child component
  67     */
  68     ResizableWindow (const String& name,
  69                      bool addToDesktop);
  70
  71     /** Creates a ResizableWindow.
  72
  73         @param name                 the name to give the component
  74         @param backgroundColour     the colour to use for filling the window's background.
  75         @param addToDesktop         if true, the window will be automatically added to the
  76                                     desktop; if false, you can use it as a child component
  77     */
  78     ResizableWindow (const String& name,
  79                      const Colour& backgroundColour,
  80                      bool addToDesktop);
  81
  82     /** Destructor.
  83         If a content component has been set with setContentOwned(), it will be deleted.
  84     */
  85     ~ResizableWindow();
  86
  87     //==============================================================================
  88     /** Returns the colour currently being used for the window's background.
  89
  90         As a convenience the window will fill itself with this colour, but you
  91         can override the paint() method if you need more customised behaviour.
  92
  93         This method is the same as retrieving the colour for ResizableWindow::backgroundColourId.
  94
  95         @see setBackgroundColour
  96     */
  97     const Colour getBackgroundColour() const noexcept;
  98
  99     /** Changes the colour currently being used for the window's background.
 100
 101         As a convenience the window will fill itself with this colour, but you
 102         can override the paint() method if you need more customised behaviour.
 103
 104         Note that the opaque state of this window is altered by this call to reflect
 105         the opacity of the colour passed-in. On window systems which can't support
 106         semi-transparent windows this might cause problems, (though it's unlikely you'll
 107         be using this class as a base for a semi-transparent component anyway).
 108
 109         You can also use the ResizableWindow::backgroundColourId colour id to set
 110         this colour.
 111
 112         @see getBackgroundColour
 113     */
 114     void setBackgroundColour (const Colour& newColour);
 115
 116     //==============================================================================
 117     /** Make the window resizable or fixed.
 118
 119         @param shouldBeResizable            whether it's resizable at all
 120         @param useBottomRightCornerResizer  if true, it'll add a ResizableCornerComponent at the
 121                                             bottom-right; if false, it'll use a ResizableBorderComponent
 122                                             around the edge
 123         @see setResizeLimits, isResizable
 124     */
 125     void setResizable (bool shouldBeResizable,
 126                        bool useBottomRightCornerResizer);
 127
 128     /** True if resizing is enabled.
 129
 130         @see setResizable
 131     */
 132     bool isResizable() const noexcept;
 133
 134     /** This sets the maximum and minimum sizes for the window.
 135
 136         If the window's current size is outside these limits, it will be resized to
 137         make sure it's within them.
 138
 139         Calling setBounds() on the component will bypass any size checking - it's only when
 140         the window is being resized by the user that these values are enforced.
 141
 142         @see setResizable, setFixedAspectRatio
 143     */
 144     void setResizeLimits (int newMinimumWidth,
 145                           int newMinimumHeight,
 146                           int newMaximumWidth,
 147                           int newMaximumHeight) noexcept;
 148
 149     /** Returns the bounds constrainer object that this window is using.
 150
 151         You can access this to change its properties.
 152     */
 153     ComponentBoundsConstrainer* getConstrainer() noexcept           { return constrainer; }
 154
 155     /** Sets the bounds-constrainer object to use for resizing and dragging this window.
 156
 157         A pointer to the object you pass in will be kept, but it won't be deleted
 158         by this object, so it's the caller's responsiblity to manage it.
 159
 160         If you pass 0, then no contraints will be placed on the positioning of the window.
 161     */
 162     void setConstrainer (ComponentBoundsConstrainer* newConstrainer);
 163
 164     /** Calls the window's setBounds method, after first checking these bounds
 165         with the current constrainer.
 166
 167         @see setConstrainer
 168     */
 169     void setBoundsConstrained (const Rectangle<int>& bounds);
 170
 171
 172     //==============================================================================
 173     /** Returns true if the window is currently in full-screen mode.
 174
 175         @see setFullScreen
 176     */
 177     bool isFullScreen() const;
 178
 179     /** Puts the window into full-screen mode, or restores it to its normal size.
 180
 181         If true, the window will become full-screen; if false, it will return to the
 182         last size it was before being made full-screen.
 183
 184         @see isFullScreen
 185     */
 186     void setFullScreen (bool shouldBeFullScreen);
 187
 188     /** Returns true if the window is currently minimised.
 189
 190         @see setMinimised
 191     */
 192     bool isMinimised() const;
 193
 194     /** Minimises the window, or restores it to its previous position and size.
 195
 196         When being un-minimised, it'll return to the last position and size it
 197         was in before being minimised.
 198
 199         @see isMinimised
 200     */
 201     void setMinimised (bool shouldMinimise);
 202
 203     /** Adds the window to the desktop using the default flags. */
 204     void addToDesktop();
 205
 206     //==============================================================================
 207     /** Returns a string which encodes the window's current size and position.
 208
 209         This string will encapsulate the window's size, position, and whether it's
 210         in full-screen mode. It's intended for letting your application save and
 211         restore a window's position.
 212
 213         Use the restoreWindowStateFromString() to restore from a saved state.
 214
 215         @see restoreWindowStateFromString
 216     */
 217     String getWindowStateAsString();
 218
 219     /** Restores the window to a previously-saved size and position.
 220
 221         This restores the window's size, positon and full-screen status from an
 222         string that was previously created with the getWindowStateAsString()
 223         method.
 224
 225         @returns false if the string wasn't a valid window state
 226         @see getWindowStateAsString
 227     */
 228     bool restoreWindowStateFromString (const String& previousState);
 229
 230
 231     //==============================================================================
 232     /** Returns the current content component.
 233
 234         This will be the component set by setContentOwned() or setContentNonOwned, or 0 if none
 235         has yet been specified.
 236
 237         @see setContentOwned, setContentNonOwned
 238     */
 239     Component* getContentComponent() const noexcept                 { return contentComponent; }
 240
 241     /** Changes the current content component.
 242
 243         This sets a component that will be placed in the centre of the ResizableWindow,
 244         (leaving a space around the edge for the border).
 245
 246         You should never add components directly to a ResizableWindow (or any of its subclasses)
 247         with addChildComponent(). Instead, add them to the content component.
 248
 249         @param newContentComponent  the new component to use - this component will be deleted when it's
 250                                     no longer needed (i.e. when the window is deleted or a new content
 251                                     component is set for it). To set a component that this window will not
 252                                     delete, call setContentNonOwned() instead.
 253         @param resizeToFitWhenContentChangesSize  if true, then the ResizableWindow will maintain its size
 254                                     such that it always fits around the size of the content component. If false,
 255                                     the new content will be resized to fit the current space available.
 256     */
 257     void setContentOwned (Component* newContentComponent,
 258                           bool resizeToFitWhenContentChangesSize);
 259
 260     /** Changes the current content component.
 261
 262         This sets a component that will be placed in the centre of the ResizableWindow,
 263         (leaving a space around the edge for the border).
 264
 265         You should never add components directly to a ResizableWindow (or any of its subclasses)
 266         with addChildComponent(). Instead, add them to the content component.
 267
 268         @param newContentComponent  the new component to use - this component will NOT be deleted by this
 269                                     component, so it's the caller's responsibility to manage its lifetime (it's
 270                                     ok to delete it while this window is still using it). To set a content
 271                                     component that the window will delete, call setContentOwned() instead.
 272         @param resizeToFitWhenContentChangesSize  if true, then the ResizableWindow will maintain its size
 273                                     such that it always fits around the size of the content component. If false,
 274                                     the new content will be resized to fit the current space available.
 275     */
 276     void setContentNonOwned (Component* newContentComponent,
 277                              bool resizeToFitWhenContentChangesSize);
 278
 279     /** Removes the current content component.
 280         If the previous content component was added with setContentOwned(), it will also be deleted. If
 281         it was added with setContentNonOwned(), it will simply be removed from this component.
 282     */
 283     void clearContentComponent();
 284
 285     /** Changes the window so that the content component ends up with the specified size.
 286
 287         This is basically a setSize call on the window, but which adds on the borders,
 288         so you can specify the content component's target size.
 289     */
 290     void setContentComponentSize (int width, int height);
 291
 292     /** Returns the width of the frame to use around the window.
 293         @see getContentComponentBorder
 294     */
 295     virtual const BorderSize<int> getBorderThickness();
 296
 297     /** Returns the insets to use when positioning the content component.
 298         @see getBorderThickness
 299     */
 300     virtual const BorderSize<int> getContentComponentBorder();
 301
 302     //==============================================================================
 303     /** A set of colour IDs to use to change the colour of various aspects of the window.
 304
 305         These constants can be used either via the Component::setColour(), or LookAndFeel::setColour()
 306         methods.
 307
 308         @see Component::setColour, Component::findColour, LookAndFeel::setColour, LookAndFeel::findColour
 309     */
 310     enum ColourIds
 311     {
 312         backgroundColourId          = 0x1005700,  /**< A colour to use to fill the window's background. */
 313     };
 314
 315     //==============================================================================
 316     /** @deprecated - use setContentOwned() and setContentNonOwned() instead. */
 317     JUCE_DEPRECATED (void setContentComponent (Component* newContentComponent,
 318                                                bool deleteOldOne = true,
 319                                                bool resizeToFit = false));
 320
 321 protected:
 322     //==============================================================================
 323     /** @internal */
 324     void paint (Graphics& g);
 325     /** (if overriding this, make sure you call ResizableWindow::resized() in your subclass) */
 326     void moved();
 327     /** (if overriding this, make sure you call ResizableWindow::resized() in your subclass) */
 328     void resized();
 329     /** @internal */
 330     void mouseDown (const MouseEvent& e);
 331     /** @internal */
 332     void mouseDrag (const MouseEvent& e);
 333     /** @internal */
 334     void lookAndFeelChanged();
 335     /** @internal */
 336     void childBoundsChanged (Component* child);
 337     /** @internal */
 338     void parentSizeChanged();
 339     /** @internal */
 340     void visibilityChanged();
 341     /** @internal */
 342     void activeWindowStatusChanged();
 343     /** @internal */
 344     int getDesktopWindowStyleFlags() const;
 345
 346    #if JUCE_DEBUG
 347     /** Overridden to warn people about adding components directly to this component
 348         instead of using setContentOwned().
 349
 350         If you know what you're doing and are sure you really want to add a component, specify
 351         a base-class method call to Component::addAndMakeVisible(), to side-step this warning.
 352     */
 353     void addChildComponent (Component* child, int zOrder = -1);
 354     /** Overridden to warn people about adding components directly to this component
 355         instead of using setContentOwned().
 356
 357         If you know what you're doing and are sure you really want to add a component, specify
 358         a base-class method call to Component::addAndMakeVisible(), to side-step this warning.
 359     */
 360     void addAndMakeVisible (Component* child, int zOrder = -1);
 361    #endif
 362
 363     ScopedPointer <ResizableCornerComponent> resizableCorner;
 364     ScopedPointer <ResizableBorderComponent> resizableBorder;
 365
 366 private:
 367     //==============================================================================
 368     Component::SafePointer <Component> contentComponent;
 369     bool ownsContentComponent, resizeToFitContent, fullscreen;
 370     ComponentDragger dragger;
 371     Rectangle<int> lastNonFullScreenPos;
 372     ComponentBoundsConstrainer defaultConstrainer;
 373     ComponentBoundsConstrainer* constrainer;
 374     #if JUCE_DEBUG
 375     bool hasBeenResized;
 376     #endif
 377
 378     void initialise (bool addToDesktop);
 379     void updateLastPos();
 380     void setContent (Component* newComp, bool takeOwnership, bool resizeToFit);
 381
 382    #if JUCE_CATCH_DEPRECATED_CODE_MISUSE
 383     // The parameters for these methods have changed - please update your code!
 384     JUCE_DEPRECATED (void getBorderThickness (int& left, int& top, int& right, int& bottom));
 385     JUCE_DEPRECATED (void getContentComponentBorder (int& left, int& top, int& right, int& bottom));
 386    #endif
 387
 388     JUCE_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR (ResizableWindow);
 389 };
 390
 391
 392 #endif   // __JUCE_RESIZABLEWINDOW_JUCEHEADER__