juce/source/src/gui/components/windows/juce_TopLevelWindow.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_TOPLEVELWINDOW_JUCEHEADER__
  27 #define __JUCE_TOPLEVELWINDOW_JUCEHEADER__
  28
  29 #include "../juce_Component.h"
  30 #include "../special/juce_DropShadower.h"
  31
  32
  33 //==============================================================================
  34 /**
  35     A base class for top-level windows.
  36
  37     This class is used for components that are considered a major part of your
  38     application - e.g. ResizableWindow, DocumentWindow, DialogWindow, AlertWindow,
  39     etc. Things like menus that pop up briefly aren't derived from it.
  40
  41     A TopLevelWindow is probably on the desktop, but this isn't mandatory - it
  42     could itself be the child of another component.
  43
  44     The class manages a list of all instances of top-level windows that are in use,
  45     and each one is also given the concept of being "active". The active window is
  46     one that is actively being used by the user. This isn't quite the same as the
  47     component with the keyboard focus, because there may be a popup menu or other
  48     temporary window which gets keyboard focus while the active top level window is
  49     unchanged.
  50
  51     A top-level window also has an optional drop-shadow.
  52
  53     @see ResizableWindow, DocumentWindow, DialogWindow
  54 */
  55 class JUCE_API  TopLevelWindow  : public Component
  56 {
  57 public:
  58     //==============================================================================
  59     /** Creates a TopLevelWindow.
  60
  61         @param name                 the name to give the component
  62         @param addToDesktop         if true, the window will be automatically added to the
  63                                     desktop; if false, you can use it as a child component
  64     */
  65     TopLevelWindow (const String& name, bool addToDesktop);
  66
  67     /** Destructor. */
  68     ~TopLevelWindow();
  69
  70     //==============================================================================
  71     /** True if this is currently the TopLevelWindow that is actively being used.
  72
  73         This isn't quite the same as having keyboard focus, because the focus may be
  74         on a child component or a temporary pop-up menu, etc, while this window is
  75         still considered to be active.
  76
  77         @see activeWindowStatusChanged
  78     */
  79     bool isActiveWindow() const noexcept                    { return windowIsActive_; }
  80
  81     //==============================================================================
  82     /** This will set the bounds of the window so that it's centred in front of another
  83         window.
  84
  85         If your app has a few windows open and want to pop up a dialog box for one of
  86         them, you can use this to show it in front of the relevent parent window, which
  87         is a bit neater than just having it appear in the middle of the screen.
  88
  89         If componentToCentreAround is 0, then the currently active TopLevelWindow will
  90         be used instead. If no window is focused, it'll just default to the middle of the
  91         screen.
  92     */
  93     void centreAroundComponent (Component* componentToCentreAround,
  94                                 int width, int height);
  95
  96     //==============================================================================
  97     /** Turns the drop-shadow on and off. */
  98     void setDropShadowEnabled (bool useShadow);
  99
 100     /** Sets whether an OS-native title bar will be used, or a Juce one.
 101
 102         @see isUsingNativeTitleBar
 103     */
 104     void setUsingNativeTitleBar (bool useNativeTitleBar);
 105
 106     /** Returns true if the window is currently using an OS-native title bar.
 107
 108         @see setUsingNativeTitleBar
 109     */
 110     bool isUsingNativeTitleBar() const noexcept             { return useNativeTitleBar && isOnDesktop(); }
 111
 112     //==============================================================================
 113     /** Returns the number of TopLevelWindow objects currently in use.
 114
 115         @see getTopLevelWindow
 116     */
 117     static int getNumTopLevelWindows() noexcept;
 118
 119     /** Returns one of the TopLevelWindow objects currently in use.
 120
 121         The index is 0 to (getNumTopLevelWindows() - 1).
 122     */
 123     static TopLevelWindow* getTopLevelWindow (int index) noexcept;
 124
 125     /** Returns the currently-active top level window.
 126
 127         There might not be one, of course, so this can return 0.
 128     */
 129     static TopLevelWindow* getActiveTopLevelWindow() noexcept;
 130
 131
 132     //==============================================================================
 133     /** @internal */
 134     virtual void addToDesktop (int windowStyleFlags, void* nativeWindowToAttachTo = nullptr);
 135
 136 protected:
 137     //==============================================================================
 138     /** This callback happens when this window becomes active or inactive.
 139
 140         @see isActiveWindow
 141     */
 142     virtual void activeWindowStatusChanged();
 143
 144
 145     //==============================================================================
 146     /** @internal */
 147     void focusOfChildComponentChanged (FocusChangeType cause);
 148     /** @internal */
 149     void parentHierarchyChanged();
 150     /** @internal */
 151     virtual int getDesktopWindowStyleFlags() const;
 152     /** @internal */
 153     void recreateDesktopWindow();
 154     /** @internal */
 155     void visibilityChanged();
 156
 157 private:
 158     friend class TopLevelWindowManager;
 159     bool useDropShadow, useNativeTitleBar, windowIsActive_;
 160     ScopedPointer <DropShadower> shadower;
 161
 162     void setWindowActive (bool isNowActive);
 163
 164     JUCE_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR (TopLevelWindow);
 165 };
 166
 167
 168 #endif   // __JUCE_TOPLEVELWINDOW_JUCEHEADER__