juce/source/src/gui/components/juce_ModalComponentManager.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_MODALCOMPONENTMANAGER_JUCEHEADER__
  27 #define __JUCE_MODALCOMPONENTMANAGER_JUCEHEADER__
  28
  29 #include "../../core/juce_Singleton.h"
  30 #include "../../events/juce_AsyncUpdater.h"
  31 #include "../../utilities/juce_DeletedAtShutdown.h"
  32
  33
  34 //==============================================================================
  35 /**
  36     Manages the system's stack of modal components.
  37
  38     Normally you'll just use the Component methods to invoke modal states in components,
  39     and won't have to deal with this class directly, but this is the singleton object that's
  40     used internally to manage the stack.
  41
  42     @see Component::enterModalState, Component::exitModalState, Component::isCurrentlyModal,
  43          Component::getCurrentlyModalComponent, Component::isCurrentlyBlockedByAnotherModalComponent
  44 */
  45 class JUCE_API  ModalComponentManager   : public AsyncUpdater,
  46                                           public DeletedAtShutdown
  47 {
  48 public:
  49     //==============================================================================
  50     /** Receives callbacks when a modal component is dismissed.
  51
  52         You can register a callback using Component::enterModalState() or
  53         ModalComponentManager::attachCallback().
  54
  55         For some quick ways of creating callback objects, see the ModalCallbackFunction class.
  56         @see ModalCallbackFunction
  57     */
  58     class Callback
  59     {
  60     public:
  61         /** */
  62         Callback() {}
  63
  64         /** Destructor. */
  65         virtual ~Callback() {}
  66
  67         /** Called to indicate that a modal component has been dismissed.
  68
  69             You can register a callback using Component::enterModalState() or
  70             ModalComponentManager::attachCallback().
  71
  72             The returnValue parameter is the value that was passed to Component::exitModalState()
  73             when the component was dismissed.
  74
  75             The callback object will be deleted shortly after this method is called.
  76         */
  77         virtual void modalStateFinished (int returnValue) = 0;
  78     };
  79
  80     //==============================================================================
  81     /** Returns the number of components currently being shown modally.
  82         @see getModalComponent
  83     */
  84     int getNumModalComponents() const;
  85
  86     /** Returns one of the components being shown modally.
  87         An index of 0 is the most recently-shown, topmost component.
  88     */
  89     Component* getModalComponent (int index) const;
  90
  91     /** Returns true if the specified component is in a modal state. */
  92     bool isModal (Component* component) const;
  93
  94     /** Returns true if the specified component is currently the topmost modal component. */
  95     bool isFrontModalComponent (Component* component) const;
  96
  97     /** Adds a new callback that will be called when the specified modal component is dismissed.
  98
  99         If the component is modal, then when it is dismissed, either by being hidden, or by calling
 100         Component::exitModalState(), then the Callback::modalStateFinished() method will be
 101         called.
 102
 103         Each component can have any number of callbacks associated with it, and this one is added
 104         to that list.
 105
 106         The object that is passed in will be deleted by the manager when it's no longer needed. If
 107         the given component is not currently modal, the callback object is deleted immediately and
 108         no action is taken.
 109     */
 110     void attachCallback (Component* component, Callback* callback);
 111
 112     /** Brings any modal components to the front. */
 113     void bringModalComponentsToFront (bool topOneShouldGrabFocus = true);
 114
 115    #if JUCE_MODAL_LOOPS_PERMITTED
 116     /** Runs the event loop until the currently topmost modal component is dismissed, and
 117         returns the exit code for that component.
 118     */
 119     int runEventLoopForCurrentComponent();
 120    #endif
 121
 122     //==============================================================================
 123     juce_DeclareSingleton_SingleThreaded_Minimal (ModalComponentManager);
 124
 125 protected:
 126     /** Creates a ModalComponentManager.
 127         You shouldn't ever call the constructor - it's a singleton, so use ModalComponentManager::getInstance()
 128     */
 129     ModalComponentManager();
 130
 131     /** Destructor. */
 132     ~ModalComponentManager();
 133
 134     /** @internal */
 135     void handleAsyncUpdate();
 136
 137 private:
 138     //==============================================================================
 139     class ModalItem;
 140     class ReturnValueRetriever;
 141
 142     friend class Component;
 143     friend class OwnedArray <ModalItem>;
 144     OwnedArray <ModalItem> stack;
 145
 146     void startModal (Component* component);
 147     void endModal (Component* component, int returnValue);
 148     void endModal (Component* component);
 149
 150     JUCE_DECLARE_NON_COPYABLE (ModalComponentManager);
 151 };
 152
 153 //==============================================================================
 154 /**
 155     This class provides some handy utility methods for creating ModalComponentManager::Callback
 156     objects that will invoke a static function with some parameters when a modal component is dismissed.
 157 */
 158 class ModalCallbackFunction
 159 {
 160 public:
 161     //==============================================================================
 162     /** This is a utility function to create a ModalComponentManager::Callback that will
 163         call a static function with a parameter.
 164
 165         The function that you supply must take two parameters - the first being an int, which is
 166         the result code that was used when the modal component was dismissed, and the second
 167         can be a custom type. Note that this custom value will be copied and stored, so it must
 168         be a primitive type or a class that provides copy-by-value semantics.
 169
 170         E.g. @code
 171         static void myCallbackFunction (int modalResult, double customValue)
 172         {
 173             if (modalResult == 1)
 174                 doSomethingWith (customValue);
 175         }
 176
 177         Component* someKindOfComp;
 178         ...
 179         someKindOfComp->enterModalState (ModalCallbackFunction::create (myCallbackFunction, 3.0));
 180         @endcode
 181         @see ModalComponentManager::Callback
 182     */
 183     template <typename ParamType>
 184     static ModalComponentManager::Callback* create (void (*functionToCall) (int, ParamType),
 185                                                     ParamType parameterValue)
 186     {
 187         return new FunctionCaller1 <ParamType> (functionToCall, parameterValue);
 188     }
 189
 190     //==============================================================================
 191     /** This is a utility function to create a ModalComponentManager::Callback that will
 192         call a static function with two custom parameters.
 193
 194         The function that you supply must take three parameters - the first being an int, which is
 195         the result code that was used when the modal component was dismissed, and the next two are
 196         your custom types. Note that these custom values will be copied and stored, so they must
 197         be primitive types or classes that provide copy-by-value semantics.
 198
 199         E.g. @code
 200         static void myCallbackFunction (int modalResult, double customValue1, String customValue2)
 201         {
 202             if (modalResult == 1)
 203                 doSomethingWith (customValue1, customValue2);
 204         }
 205
 206         Component* someKindOfComp;
 207         ...
 208         someKindOfComp->enterModalState (ModalCallbackFunction::create (myCallbackFunction, 3.0, String ("xyz")));
 209         @endcode
 210         @see ModalComponentManager::Callback
 211     */
 212     template <typename ParamType1, typename ParamType2>
 213     static ModalComponentManager::Callback* withParam (void (*functionToCall) (int, ParamType1, ParamType2),
 214                                                        ParamType1 parameterValue1,
 215                                                        ParamType2 parameterValue2)
 216     {
 217         return new FunctionCaller2 <ParamType1, ParamType2> (functionToCall, parameterValue1, parameterValue2);
 218     }
 219
 220     //==============================================================================
 221     /** This is a utility function to create a ModalComponentManager::Callback that will
 222         call a static function with a component.
 223
 224         The function that you supply must take two parameters - the first being an int, which is
 225         the result code that was used when the modal component was dismissed, and the second
 226         can be a Component class. The component will be stored as a WeakReference, so that if it gets
 227         deleted before this callback is invoked, the pointer that is passed to the function will be null.
 228
 229         E.g. @code
 230         static void myCallbackFunction (int modalResult, Slider* mySlider)
 231         {
 232             if (modalResult == 1 && mySlider != nullptr) // (must check that mySlider isn't null in case it was deleted..)
 233                 mySlider->setValue (0.0);
 234         }
 235
 236         Component* someKindOfComp;
 237         Slider* mySlider;
 238         ...
 239         someKindOfComp->enterModalState (ModalCallbackFunction::forComponent (myCallbackFunction, mySlider));
 240         @endcode
 241         @see ModalComponentManager::Callback
 242     */
 243     template <class ComponentType>
 244     static ModalComponentManager::Callback* forComponent (void (*functionToCall) (int, ComponentType*),
 245                                                           ComponentType* component)
 246     {
 247         return new ComponentCaller1 <ComponentType> (functionToCall, component);
 248     }
 249
 250     //==============================================================================
 251     /** Creates a ModalComponentManager::Callback that will call a static function with a component.
 252
 253         The function that you supply must take three parameters - the first being an int, which is
 254         the result code that was used when the modal component was dismissed, the second being a Component
 255         class, and the third being a custom type (which must be a primitive type or have copy-by-value semantics).
 256         The component will be stored as a WeakReference, so that if it gets deleted before this callback is
 257         invoked, the pointer that is passed into the function will be null.
 258
 259         E.g. @code
 260         static void myCallbackFunction (int modalResult, Slider* mySlider, String customParam)
 261         {
 262             if (modalResult == 1 && mySlider != nullptr) // (must check that mySlider isn't null in case it was deleted..)
 263                 mySlider->setName (customParam);
 264         }
 265
 266         Component* someKindOfComp;
 267         Slider* mySlider;
 268         ...
 269         someKindOfComp->enterModalState (ModalCallbackFunction::forComponent (myCallbackFunction, mySlider, String ("hello")));
 270         @endcode
 271         @see ModalComponentManager::Callback
 272     */
 273     template <class ComponentType, typename ParamType>
 274     static ModalComponentManager::Callback* forComponent (void (*functionToCall) (int, ComponentType*, ParamType),
 275                                                           ComponentType* component,
 276                                                           ParamType param)
 277     {
 278         return new ComponentCaller2 <ComponentType, ParamType> (functionToCall, component, param);
 279     }
 280
 281 private:
 282     //==============================================================================
 283     template <typename ParamType>
 284     class FunctionCaller1  : public ModalComponentManager::Callback
 285     {
 286     public:
 287         typedef void (*FunctionType) (int, ParamType);
 288
 289         FunctionCaller1 (FunctionType& function_, ParamType& param_)
 290             : function (function_), param (param_) {}
 291
 292         void modalStateFinished (int returnValue)  { function (returnValue, param); }
 293
 294     private:
 295         const FunctionType function;
 296         ParamType param;
 297
 298         JUCE_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR (FunctionCaller1);
 299     };
 300
 301     template <typename ParamType1, typename ParamType2>
 302     class FunctionCaller2  : public ModalComponentManager::Callback
 303     {
 304     public:
 305         typedef void (*FunctionType) (int, ParamType1, ParamType2);
 306
 307         FunctionCaller2 (FunctionType& function_, ParamType1& param1_, ParamType2& param2_)
 308             : function (function_), param1 (param1_), param2 (param2_) {}
 309
 310         void modalStateFinished (int returnValue)   { function (returnValue, param1, param2); }
 311
 312     private:
 313         const FunctionType function;
 314         ParamType1 param1;
 315         ParamType2 param2;
 316
 317         JUCE_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR (FunctionCaller2);
 318     };
 319
 320     template <typename ComponentType>
 321     class ComponentCaller1  : public ModalComponentManager::Callback
 322     {
 323     public:
 324         typedef void (*FunctionType) (int, ComponentType*);
 325
 326         ComponentCaller1 (FunctionType& function_, ComponentType* comp_)
 327             : function (function_), comp (comp_) {}
 328
 329         void modalStateFinished (int returnValue)
 330         {
 331             function (returnValue, static_cast <ComponentType*> (comp.get()));
 332         }
 333
 334     private:
 335         const FunctionType function;
 336         WeakReference<Component> comp;
 337
 338         JUCE_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR (ComponentCaller1);
 339     };
 340
 341     template <typename ComponentType, typename ParamType1>
 342     class ComponentCaller2  : public ModalComponentManager::Callback
 343     {
 344     public:
 345         typedef void (*FunctionType) (int, ComponentType*, ParamType1);
 346
 347         ComponentCaller2 (FunctionType& function_, ComponentType* comp_, ParamType1 param1_)
 348             : function (function_), comp (comp_), param1 (param1_) {}
 349
 350         void modalStateFinished (int returnValue)
 351         {
 352             function (returnValue, static_cast <ComponentType*> (comp.get()), param1);
 353         }
 354
 355     private:
 356         const FunctionType function;
 357         WeakReference<Component> comp;
 358         ParamType1 param1;
 359
 360         JUCE_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR (ComponentCaller2);
 361     };
 362
 363     ModalCallbackFunction();
 364     ~ModalCallbackFunction();
 365     JUCE_DECLARE_NON_COPYABLE (ModalCallbackFunction);
 366 };
 367
 368
 369 #endif   // __JUCE_MODALCOMPONENTMANAGER_JUCEHEADER__