juce/source/src/gui/components/windows/juce_ComponentPeer.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_COMPONENTPEER_JUCEHEADER__
  27 #define __JUCE_COMPONENTPEER_JUCEHEADER__
  28
  29 #include "../juce_Component.h"
  30 #include "../mouse/juce_MouseCursor.h"
  31 #include "../keyboard/juce_TextInputTarget.h"
  32 #include "../../../text/juce_StringArray.h"
  33 #include "../../graphics/geometry/juce_RectangleList.h"
  34
  35 class ComponentBoundsConstrainer;
  36
  37
  38 //==============================================================================
  39 /**
  40     The Component class uses a ComponentPeer internally to create and manage a real
  41     operating-system window.
  42
  43     This is an abstract base class - the platform specific code contains implementations of
  44     it for the various platforms.
  45
  46     User-code should very rarely need to have any involvement with this class.
  47
  48     @see Component::createNewPeer
  49 */
  50 class JUCE_API  ComponentPeer
  51 {
  52 public:
  53     //==============================================================================
  54     /** A combination of these flags is passed to the ComponentPeer constructor. */
  55     enum StyleFlags
  56     {
  57         windowAppearsOnTaskbar      = (1 << 0),    /**< Indicates that the window should have a corresponding
  58                                                         entry on the taskbar (ignored on MacOSX) */
  59         windowIsTemporary           = (1 << 1),    /**< Indicates that the window is a temporary popup, like a menu,
  60                                                         tooltip, etc. */
  61         windowIgnoresMouseClicks    = (1 << 2),    /**< Indicates that the window should let mouse clicks pass
  62                                                         through it (may not be possible on some platforms). */
  63         windowHasTitleBar           = (1 << 3),    /**< Indicates that the window should have a normal OS-specific
  64                                                         title bar and frame\. if not specified, the window will be
  65                                                         borderless. */
  66         windowIsResizable           = (1 << 4),    /**< Indicates that the window should have a resizable border. */
  67         windowHasMinimiseButton     = (1 << 5),    /**< Indicates that if the window has a title bar, it should have a
  68                                                         minimise button on it. */
  69         windowHasMaximiseButton     = (1 << 6),    /**< Indicates that if the window has a title bar, it should have a
  70                                                         maximise button on it. */
  71         windowHasCloseButton        = (1 << 7),    /**< Indicates that if the window has a title bar, it should have a
  72                                                         close button on it. */
  73         windowHasDropShadow         = (1 << 8),    /**< Indicates that the window should have a drop-shadow (this may
  74                                                         not be possible on all platforms). */
  75         windowRepaintedExplictly    = (1 << 9),    /**< Not intended for public use - this tells a window not to
  76                                                         do its own repainting, but only to repaint when the
  77                                                         performAnyPendingRepaintsNow() method is called. */
  78         windowIgnoresKeyPresses     = (1 << 10),   /**< Tells the window not to catch any keypresses. This can
  79                                                         be used for things like plugin windows, to stop them interfering
  80                                                         with the host's shortcut keys */
  81         windowIsSemiTransparent     = (1 << 31)    /**< Not intended for public use - makes a window transparent. */
  82
  83     };
  84
  85     //==============================================================================
  86     /** Creates a peer.
  87
  88         The component is the one that we intend to represent, and the style flags are
  89         a combination of the values in the StyleFlags enum
  90     */
  91     ComponentPeer (Component* component, int styleFlags);
  92
  93     /** Destructor. */
  94     virtual ~ComponentPeer();
  95
  96     //==============================================================================
  97     /** Returns the component being represented by this peer. */
  98     Component* getComponent() const noexcept                { return component; }
  99
 100     /** Returns the set of style flags that were set when the window was created.
 101
 102         @see Component::addToDesktop
 103     */
 104     int getStyleFlags() const noexcept                      { return styleFlags; }
 105
 106     /** Returns a unique ID for this peer.
 107         Each peer that is created is given a different ID.
 108     */
 109     uint32 getUniqueID() const noexcept                     { return uniqueID; }
 110
 111     //==============================================================================
 112     /** Returns the raw handle to whatever kind of window is being used.
 113
 114         On windows, this is probably a HWND, on the mac, it's likely to be a WindowRef,
 115         but rememeber there's no guarantees what you'll get back.
 116     */
 117     virtual void* getNativeHandle() const = 0;
 118
 119     /** Shows or hides the window. */
 120     virtual void setVisible (bool shouldBeVisible) = 0;
 121
 122     /** Changes the title of the window. */
 123     virtual void setTitle (const String& title) = 0;
 124
 125     /** Moves the window without changing its size.
 126
 127         If the native window is contained in another window, then the co-ordinates are
 128         relative to the parent window's origin, not the screen origin.
 129
 130         This should result in a callback to handleMovedOrResized().
 131     */
 132     virtual void setPosition (int x, int y) = 0;
 133
 134     /** Resizes the window without changing its position.
 135
 136         This should result in a callback to handleMovedOrResized().
 137     */
 138     virtual void setSize (int w, int h) = 0;
 139
 140     /** Moves and resizes the window.
 141
 142         If the native window is contained in another window, then the co-ordinates are
 143         relative to the parent window's origin, not the screen origin.
 144
 145         This should result in a callback to handleMovedOrResized().
 146     */
 147     virtual void setBounds (int x, int y, int w, int h, bool isNowFullScreen) = 0;
 148
 149     /** Returns the current position and size of the window.
 150
 151         If the native window is contained in another window, then the co-ordinates are
 152         relative to the parent window's origin, not the screen origin.
 153     */
 154     virtual const Rectangle<int> getBounds() const = 0;
 155
 156     /** Returns the x-position of this window, relative to the screen's origin. */
 157     virtual const Point<int> getScreenPosition() const = 0;
 158
 159     /** Converts a position relative to the top-left of this component to screen co-ordinates. */
 160     virtual const Point<int> localToGlobal (const Point<int>& relativePosition) = 0;
 161
 162     /** Converts a rectangle relative to the top-left of this component to screen co-ordinates. */
 163     virtual const Rectangle<int> localToGlobal (const Rectangle<int>& relativePosition);
 164
 165     /** Converts a screen co-ordinate to a position relative to the top-left of this component. */
 166     virtual const Point<int> globalToLocal (const Point<int>& screenPosition) = 0;
 167
 168     /** Converts a screen area to a position relative to the top-left of this component. */
 169     virtual const Rectangle<int> globalToLocal (const Rectangle<int>& screenPosition);
 170
 171     /** Minimises the window. */
 172     virtual void setMinimised (bool shouldBeMinimised) = 0;
 173
 174     /** True if the window is currently minimised. */
 175     virtual bool isMinimised() const = 0;
 176
 177     /** Enable/disable fullscreen mode for the window. */
 178     virtual void setFullScreen (bool shouldBeFullScreen) = 0;
 179
 180     /** True if the window is currently full-screen. */
 181     virtual bool isFullScreen() const = 0;
 182
 183     /** Sets the size to restore to if fullscreen mode is turned off. */
 184     void setNonFullScreenBounds (const Rectangle<int>& newBounds) noexcept;
 185
 186     /** Returns the size to restore to if fullscreen mode is turned off. */
 187     const Rectangle<int>& getNonFullScreenBounds() const noexcept;
 188
 189     /** Attempts to change the icon associated with this window.
 190     */
 191     virtual void setIcon (const Image& newIcon) = 0;
 192
 193     /** Sets a constrainer to use if the peer can resize itself.
 194
 195         The constrainer won't be deleted by this object, so the caller must manage its lifetime.
 196     */
 197     void setConstrainer (ComponentBoundsConstrainer* newConstrainer) noexcept;
 198
 199     /** Returns the current constrainer, if one has been set. */
 200     ComponentBoundsConstrainer* getConstrainer() const noexcept             { return constrainer; }
 201
 202     /** Checks if a point is in the window.
 203
 204         Coordinates are relative to the top-left of this window. If trueIfInAChildWindow
 205         is false, then this returns false if the point is actually inside a child of this
 206         window.
 207     */
 208     virtual bool contains (const Point<int>& position, bool trueIfInAChildWindow) const = 0;
 209
 210     /** Returns the size of the window frame that's around this window.
 211
 212         Whether or not the window has a normal window frame depends on the flags
 213         that were set when the window was created by Component::addToDesktop()
 214     */
 215     virtual const BorderSize<int> getFrameSize() const = 0;
 216
 217     /** This is called when the window's bounds change.
 218
 219         A peer implementation must call this when the window is moved and resized, so that
 220         this method can pass the message on to the component.
 221     */
 222     void handleMovedOrResized();
 223
 224     /** This is called if the screen resolution changes.
 225
 226         A peer implementation must call this if the monitor arrangement changes or the available
 227         screen size changes.
 228     */
 229     void handleScreenSizeChange();
 230
 231     //==============================================================================
 232     /** This is called to repaint the component into the given context. */
 233     void handlePaint (LowLevelGraphicsContext& contextToPaintTo);
 234
 235     //==============================================================================
 236     /** Sets this window to either be always-on-top or normal.
 237
 238         Some kinds of window might not be able to do this, so should return false.
 239     */
 240     virtual bool setAlwaysOnTop (bool alwaysOnTop) = 0;
 241
 242     /** Brings the window to the top, optionally also giving it focus. */
 243     virtual void toFront (bool makeActive) = 0;
 244
 245     /** Moves the window to be just behind another one. */
 246     virtual void toBehind (ComponentPeer* other) = 0;
 247
 248     /** Called when the window is brought to the front, either by the OS or by a call
 249         to toFront().
 250     */
 251     void handleBroughtToFront();
 252
 253     //==============================================================================
 254     /** True if the window has the keyboard focus. */
 255     virtual bool isFocused() const = 0;
 256
 257     /** Tries to give the window keyboard focus. */
 258     virtual void grabFocus() = 0;
 259
 260     /** Called when the window gains keyboard focus. */
 261     void handleFocusGain();
 262     /** Called when the window loses keyboard focus. */
 263     void handleFocusLoss();
 264
 265     Component* getLastFocusedSubcomponent() const noexcept;
 266
 267     /** Called when a key is pressed.
 268
 269         For keycode info, see the KeyPress class.
 270         Returns true if the keystroke was used.
 271     */
 272     bool handleKeyPress (int keyCode, juce_wchar textCharacter);
 273
 274     /** Called whenever a key is pressed or released.
 275         Returns true if the keystroke was used.
 276     */
 277     bool handleKeyUpOrDown (bool isKeyDown);
 278
 279     /** Called whenever a modifier key is pressed or released. */
 280     void handleModifierKeysChange();
 281
 282     //==============================================================================
 283     /** Tells the window that text input may be required at the given position.
 284         This may cause things like a virtual on-screen keyboard to appear, depending
 285         on the OS.
 286     */
 287     virtual void textInputRequired (const Point<int>& position) = 0;
 288
 289     /** If there's some kind of OS input-method in progress, this should dismiss it. */
 290     virtual void dismissPendingTextInput();
 291
 292     /** Returns the currently focused TextInputTarget, or null if none is found. */
 293     TextInputTarget* findCurrentTextInputTarget();
 294
 295     //==============================================================================
 296     /** Invalidates a region of the window to be repainted asynchronously. */
 297     virtual void repaint (const Rectangle<int>& area) = 0;
 298
 299     /** This can be called (from the message thread) to cause the immediate redrawing
 300         of any areas of this window that need repainting.
 301
 302         You shouldn't ever really need to use this, it's mainly for special purposes
 303         like supporting audio plugins where the host's event loop is out of our control.
 304     */
 305     virtual void performAnyPendingRepaintsNow() = 0;
 306
 307     /** Changes the window's transparency. */
 308     virtual void setAlpha (float newAlpha) = 0;
 309
 310     //==============================================================================
 311     void handleMouseEvent (int touchIndex, const Point<int>& positionWithinPeer, const ModifierKeys& newMods, int64 time);
 312     void handleMouseWheel (int touchIndex, const Point<int>& positionWithinPeer, int64 time, float x, float y);
 313
 314     void handleUserClosingWindow();
 315
 316     void handleFileDragMove (const StringArray& files, const Point<int>& position);
 317     void handleFileDragExit (const StringArray& files);
 318     void handleFileDragDrop (const StringArray& files, const Point<int>& position);
 319
 320     //==============================================================================
 321     /** Resets the masking region.
 322
 323         The subclass should call this every time it's about to call the handlePaint
 324         method.
 325
 326         @see addMaskedRegion
 327     */
 328     void clearMaskedRegion();
 329
 330     /** Adds a rectangle to the set of areas not to paint over.
 331
 332         A component can call this on its peer during its paint() method, to signal
 333         that the painting code should ignore a given region. The reason
 334         for this is to stop embedded windows (such as OpenGL) getting painted over.
 335
 336         The masked region is cleared each time before a paint happens, so a component
 337         will have to make sure it calls this every time it's painted.
 338     */
 339     void addMaskedRegion (int x, int y, int w, int h);
 340
 341     //==============================================================================
 342     /** Returns the number of currently-active peers.
 343
 344         @see getPeer
 345     */
 346     static int getNumPeers() noexcept;
 347
 348     /** Returns one of the currently-active peers.
 349
 350         @see getNumPeers
 351     */
 352     static ComponentPeer* getPeer (int index) noexcept;
 353
 354     /** Checks if this peer object is valid.
 355
 356         @see getNumPeers
 357     */
 358     static bool isValidPeer (const ComponentPeer* peer) noexcept;
 359
 360
 361     //==============================================================================
 362     virtual StringArray getAvailableRenderingEngines();
 363     virtual int getCurrentRenderingEngine() const;
 364     virtual void setCurrentRenderingEngine (int index);
 365
 366 protected:
 367     //==============================================================================
 368     Component* const component;
 369     const int styleFlags;
 370     RectangleList maskedRegion;
 371     Rectangle<int> lastNonFullscreenBounds;
 372     uint32 lastPaintTime;
 373     ComponentBoundsConstrainer* constrainer;
 374
 375     static void updateCurrentModifiers() noexcept;
 376
 377 private:
 378     //==============================================================================
 379     WeakReference<Component> lastFocusedComponent, dragAndDropTargetComponent;
 380     Component* lastDragAndDropCompUnderMouse;
 381     const uint32 uniqueID;
 382     bool fakeMouseMessageSent : 1, isWindowMinimised : 1;
 383
 384     friend class Component;
 385     friend class Desktop;
 386     static ComponentPeer* getPeerFor (const Component* component) noexcept;
 387
 388     void setLastDragDropTarget (Component* comp);
 389
 390     JUCE_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR (ComponentPeer);
 391 };
 392
 393
 394 #endif   // __JUCE_COMPONENTPEER_JUCEHEADER__