juce/source/src/gui/components/juce_Desktop.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_DESKTOP_JUCEHEADER__
  27 #define __JUCE_DESKTOP_JUCEHEADER__
  28
  29 #include "juce_Component.h"
  30 #include "../../utilities/juce_DeletedAtShutdown.h"
  31 #include "../../events/juce_Timer.h"
  32 #include "../../events/juce_AsyncUpdater.h"
  33 #include "../../containers/juce_OwnedArray.h"
  34 #include "../graphics/geometry/juce_RectangleList.h"
  35 #include "layout/juce_ComponentAnimator.h"
  36 class MouseInputSource;
  37 class MouseInputSourceInternal;
  38 class MouseListener;
  39
  40
  41 //==============================================================================
  42 /**
  43     Classes can implement this interface and register themselves with the Desktop class
  44     to receive callbacks when the currently focused component changes.
  45
  46     @see Desktop::addFocusChangeListener, Desktop::removeFocusChangeListener
  47 */
  48 class JUCE_API  FocusChangeListener
  49 {
  50 public:
  51     /** Destructor. */
  52     virtual ~FocusChangeListener()  {}
  53
  54     /** Callback to indicate that the currently focused component has changed. */
  55     virtual void globalFocusChanged (Component* focusedComponent) = 0;
  56 };
  57
  58
  59 //==============================================================================
  60 /**
  61     Describes and controls aspects of the computer's desktop.
  62
  63 */
  64 class JUCE_API  Desktop  : private DeletedAtShutdown,
  65                            private Timer,
  66                            private AsyncUpdater
  67 {
  68 public:
  69     //==============================================================================
  70     /** There's only one dektop object, and this method will return it.
  71     */
  72     static Desktop& JUCE_CALLTYPE getInstance();
  73
  74     //==============================================================================
  75     /** Returns a list of the positions of all the monitors available.
  76
  77         The first rectangle in the list will be the main monitor area.
  78
  79         If clippedToWorkArea is true, it will exclude any areas like the taskbar on Windows,
  80         or the menu bar on Mac. If clippedToWorkArea is false, the entire monitor area is returned.
  81     */
  82     const RectangleList getAllMonitorDisplayAreas (bool clippedToWorkArea = true) const;
  83
  84     /** Returns the position and size of the main monitor.
  85
  86         If clippedToWorkArea is true, it will exclude any areas like the taskbar on Windows,
  87         or the menu bar on Mac. If clippedToWorkArea is false, the entire monitor area is returned.
  88     */
  89     const Rectangle<int> getMainMonitorArea (bool clippedToWorkArea = true) const noexcept;
  90
  91     /** Returns the position and size of the monitor which contains this co-ordinate.
  92
  93         If none of the monitors contains the point, this will just return the
  94         main monitor.
  95
  96         If clippedToWorkArea is true, it will exclude any areas like the taskbar on Windows,
  97         or the menu bar on Mac. If clippedToWorkArea is false, the entire monitor area is returned.
  98     */
  99     const Rectangle<int> getMonitorAreaContaining (const Point<int>& position, bool clippedToWorkArea = true) const;
 100
 101
 102     //==============================================================================
 103     /** Returns the mouse position.
 104
 105         The co-ordinates are relative to the top-left of the main monitor.
 106
 107         Note that this is just a shortcut for calling getMainMouseSource().getScreenPosition(), and
 108         you should only resort to grabbing the global mouse position if there's really no
 109         way to get the coordinates via a mouse event callback instead.
 110     */
 111     static const Point<int> getMousePosition();
 112
 113     /** Makes the mouse pointer jump to a given location.
 114
 115         The co-ordinates are relative to the top-left of the main monitor.
 116     */
 117     static void setMousePosition (const Point<int>& newPosition);
 118
 119     /** Returns the last position at which a mouse button was pressed.
 120
 121         Note that this is just a shortcut for calling getMainMouseSource().getLastMouseDownPosition(),
 122         and in a multi-touch environment, it doesn't make much sense. ALWAYS prefer to
 123         get this information via other means, such as MouseEvent::getMouseDownScreenPosition()
 124         if possible, and only ever call this as a last resort.
 125     */
 126     static const Point<int> getLastMouseDownPosition();
 127
 128     /** Returns the number of times the mouse button has been clicked since the
 129         app started.
 130
 131         Each mouse-down event increments this number by 1.
 132     */
 133     static int getMouseButtonClickCounter();
 134
 135     //==============================================================================
 136     /** This lets you prevent the screensaver from becoming active.
 137
 138         Handy if you're running some sort of presentation app where having a screensaver
 139         appear would be annoying.
 140
 141         Pass false to disable the screensaver, and true to re-enable it. (Note that this
 142         won't enable a screensaver unless the user has actually set one up).
 143
 144         The disablement will only happen while the Juce application is the foreground
 145         process - if another task is running in front of it, then the screensaver will
 146         be unaffected.
 147
 148         @see isScreenSaverEnabled
 149     */
 150     static void setScreenSaverEnabled (bool isEnabled);
 151
 152     /** Returns true if the screensaver has not been turned off.
 153
 154         This will return the last value passed into setScreenSaverEnabled(). Note that
 155         it won't tell you whether the user is actually using a screen saver, just
 156         whether this app is deliberately preventing one from running.
 157
 158         @see setScreenSaverEnabled
 159     */
 160     static bool isScreenSaverEnabled();
 161
 162     //==============================================================================
 163     /** Registers a MouseListener that will receive all mouse events that occur on
 164         any component.
 165
 166         @see removeGlobalMouseListener
 167     */
 168     void addGlobalMouseListener (MouseListener* listener);
 169
 170     /** Unregisters a MouseListener that was added with the addGlobalMouseListener()
 171         method.
 172
 173         @see addGlobalMouseListener
 174     */
 175     void removeGlobalMouseListener (MouseListener* listener);
 176
 177     //==============================================================================
 178     /** Registers a MouseListener that will receive a callback whenever the focused
 179         component changes.
 180     */
 181     void addFocusChangeListener (FocusChangeListener* listener);
 182
 183     /** Unregisters a listener that was added with addFocusChangeListener(). */
 184     void removeFocusChangeListener (FocusChangeListener* listener);
 185
 186     //==============================================================================
 187     /** Takes a component and makes it full-screen, removing the taskbar, dock, etc.
 188
 189         The component must already be on the desktop for this method to work. It will
 190         be resized to completely fill the screen and any extraneous taskbars, menu bars,
 191         etc will be hidden.
 192
 193         To exit kiosk mode, just call setKioskModeComponent (nullptr). When this is called,
 194         the component that's currently being used will be resized back to the size
 195         and position it was in before being put into this mode.
 196
 197         If allowMenusAndBars is true, things like the menu and dock (on mac) are still
 198         allowed to pop up when the mouse moves onto them. If this is false, it'll try
 199         to hide as much on-screen paraphenalia as possible.
 200     */
 201     void setKioskModeComponent (Component* componentToUse,
 202                                 bool allowMenusAndBars = true);
 203
 204     /** Returns the component that is currently being used in kiosk-mode.
 205
 206         This is the component that was last set by setKioskModeComponent(). If none
 207         has been set, this returns 0.
 208     */
 209     Component* getKioskModeComponent() const noexcept               { return kioskModeComponent; }
 210
 211     //==============================================================================
 212     /** Returns the number of components that are currently active as top-level
 213         desktop windows.
 214
 215         @see getComponent, Component::addToDesktop
 216     */
 217     int getNumComponents() const noexcept;
 218
 219     /** Returns one of the top-level desktop window components.
 220
 221         The index is from 0 to getNumComponents() - 1. This could return 0 if the
 222         index is out-of-range.
 223
 224         @see getNumComponents, Component::addToDesktop
 225     */
 226     Component* getComponent (int index) const noexcept;
 227
 228     /** Finds the component at a given screen location.
 229
 230         This will drill down into top-level windows to find the child component at
 231         the given position.
 232
 233         Returns 0 if the co-ordinates are inside a non-Juce window.
 234     */
 235     Component* findComponentAt (const Point<int>& screenPosition) const;
 236
 237     /** The Desktop object has a ComponentAnimator instance which can be used for performing
 238         your animations.
 239
 240         Having a single shared ComponentAnimator object makes it more efficient when multiple
 241         components are being moved around simultaneously. It's also more convenient than having
 242         to manage your own instance of one.
 243
 244         @see ComponentAnimator
 245     */
 246     ComponentAnimator& getAnimator() noexcept                       { return animator; }
 247
 248     //==============================================================================
 249     /** Returns the current default look-and-feel for components which don't have one
 250         explicitly set.
 251         @see setDefaultLookAndFeel
 252     */
 253     LookAndFeel& getDefaultLookAndFeel() noexcept;
 254
 255     /** Changes the default look-and-feel.
 256         @param newDefaultLookAndFeel    the new look-and-feel object to use - if this is
 257                                         set to nullptr, it will revert to using the system's
 258                                         default one. The object passed-in must be deleted by the
 259                                         caller when it's no longer needed.
 260         @see getDefaultLookAndFeel
 261     */
 262     void setDefaultLookAndFeel (LookAndFeel* newDefaultLookAndFeel);
 263
 264     //==============================================================================
 265     /** Returns the number of MouseInputSource objects the system has at its disposal.
 266         In a traditional single-mouse system, there might be only one object. On a multi-touch
 267         system, there could be one input source per potential finger.
 268         To find out how many mouse events are currently happening, use getNumDraggingMouseSources().
 269         @see getMouseSource
 270     */
 271     int getNumMouseSources() const noexcept                         { return mouseSources.size(); }
 272
 273     /** Returns one of the system's MouseInputSource objects.
 274         The index should be from 0 to getNumMouseSources() - 1. Out-of-range indexes will return
 275         a null pointer.
 276         In a traditional single-mouse system, there might be only one object. On a multi-touch
 277         system, there could be one input source per potential finger.
 278     */
 279     MouseInputSource* getMouseSource (int index) const noexcept     { return mouseSources [index]; }
 280
 281     /** Returns the main mouse input device that the system is using.
 282         @see getNumMouseSources()
 283     */
 284     MouseInputSource& getMainMouseSource() const noexcept           { return *mouseSources.getUnchecked(0); }
 285
 286     /** Returns the number of mouse-sources that are currently being dragged.
 287         In a traditional single-mouse system, this will be 0 or 1, depending on whether a
 288         juce component has the button down on it. In a multi-touch system, this could
 289         be any number from 0 to the number of simultaneous touches that can be detected.
 290     */
 291     int getNumDraggingMouseSources() const noexcept;
 292
 293     /** Returns one of the mouse sources that's currently being dragged.
 294         The index should be between 0 and getNumDraggingMouseSources() - 1. If the index is
 295         out of range, or if no mice or fingers are down, this will return a null pointer.
 296     */
 297     MouseInputSource* getDraggingMouseSource (int index) const noexcept;
 298
 299     /** Ensures that a non-stop stream of mouse-drag events will be sent during the
 300         current mouse-drag operation.
 301
 302         This allows you to make sure that mouseDrag() events are sent continuously, even
 303         when the mouse isn't moving. This can be useful for things like auto-scrolling
 304         components when the mouse is near an edge.
 305
 306         Call this method during a mouseDown() or mouseDrag() callback, specifying the
 307         minimum interval between consecutive mouse drag callbacks. The callbacks
 308         will continue until the mouse is released, and then the interval will be reset,
 309         so you need to make sure it's called every time you begin a drag event.
 310         Passing an interval of 0 or less will cancel the auto-repeat.
 311
 312         @see mouseDrag
 313     */
 314     void beginDragAutoRepeat (int millisecondsBetweenCallbacks);
 315
 316     //==============================================================================
 317     /** In a tablet device which can be turned around, this is used to inidicate the orientation. */
 318     enum DisplayOrientation
 319     {
 320         upright                 = 1,  /**< Indicates that the display is the normal way up. */
 321         upsideDown              = 2,  /**< Indicates that the display is upside-down. */
 322         rotatedClockwise        = 4,  /**< Indicates that the display is turned 90 degrees clockwise from its upright position. */
 323         rotatedAntiClockwise    = 8,  /**< Indicates that the display is turned 90 degrees anti-clockwise from its upright position. */
 324
 325         allOrientations         = 1 + 2 + 4 + 8   /**< A combination of all the orientation values */
 326     };
 327
 328     /** In a tablet device which can be turned around, this returns the current orientation. */
 329     DisplayOrientation getCurrentOrientation() const;
 330
 331     /** Sets which orientations the display is allowed to auto-rotate to.
 332
 333         For devices that support rotating desktops, this lets you specify which of the orientations your app can use.
 334
 335         The parameter is a bitwise or-ed combination of the values in DisplayOrientation, and must contain at least one
 336         set bit.
 337     */
 338     void setOrientationsEnabled (int allowedOrientations);
 339
 340     /** Returns whether the display is allowed to auto-rotate to the given orientation.
 341         Each orientation can be enabled using setOrientationEnabled(). By default, all orientations are allowed.
 342     */
 343     bool isOrientationEnabled (DisplayOrientation orientation) const noexcept;
 344
 345     //==============================================================================
 346     /** Tells this object to refresh its idea of what the screen resolution is.
 347
 348         (Called internally by the native code).
 349     */
 350     void refreshMonitorSizes();
 351
 352     /** True if the OS supports semitransparent windows */
 353     static bool canUseSemiTransparentWindows() noexcept;
 354
 355 private:
 356     //==============================================================================
 357     static Desktop* instance;
 358
 359     friend class Component;
 360     friend class ComponentPeer;
 361     friend class MouseInputSource;
 362     friend class MouseInputSourceInternal;
 363     friend class DeletedAtShutdown;
 364     friend class TopLevelWindowManager;
 365
 366     OwnedArray <MouseInputSource> mouseSources;
 367     void createMouseInputSources();
 368
 369     ListenerList <MouseListener> mouseListeners;
 370     ListenerList <FocusChangeListener> focusListeners;
 371
 372     Array <Component*> desktopComponents;
 373     Array <Rectangle<int> > monitorCoordsClipped, monitorCoordsUnclipped;
 374
 375     Point<int> lastFakeMouseMove;
 376     void sendMouseMove();
 377
 378     int mouseClickCounter;
 379     void incrementMouseClickCounter() noexcept;
 380
 381     ScopedPointer<Timer> dragRepeater;
 382
 383     ScopedPointer<LookAndFeel> defaultLookAndFeel;
 384     WeakReference<LookAndFeel> currentLookAndFeel;
 385
 386     Component* kioskModeComponent;
 387     Rectangle<int> kioskComponentOriginalBounds;
 388
 389     int allowedOrientations;
 390
 391     ComponentAnimator animator;
 392
 393     void timerCallback();
 394     void resetTimer();
 395
 396     int getNumDisplayMonitors() const noexcept;
 397     const Rectangle<int> getDisplayMonitorCoordinates (int index, bool clippedToWorkArea) const noexcept;
 398     static void getCurrentMonitorPositions (Array <Rectangle<int> >& monitorCoords, const bool clipToWorkArea);
 399
 400     void addDesktopComponent (Component* c);
 401     void removeDesktopComponent (Component* c);
 402     void componentBroughtToFront (Component* c);
 403
 404     static void setKioskComponent (Component* kioskModeComponent, bool enableOrDisable, bool allowMenusAndBars);
 405
 406     void triggerFocusCallback();
 407     void handleAsyncUpdate();
 408
 409     Desktop();
 410     ~Desktop();
 411
 412     JUCE_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR (Desktop);
 413 };
 414
 415
 416 #endif   // __JUCE_DESKTOP_JUCEHEADER__