source/modules/juce_gui_basics/windows/juce_TopLevelWindow.h

   1 /*
   2   ==============================================================================
   3
   4    This file is part of the JUCE library.
   5    Copyright (c) 2022 - Raw Material Software Limited
   6
   7    JUCE is an open source library subject to commercial or open-source
   8    licensing.
   9
  10    By using JUCE, you agree to the terms of both the JUCE 7 End-User License
  11    Agreement and JUCE Privacy Policy.
  12
  13    End User License Agreement: www.juce.com/juce-7-licence
  14    Privacy Policy: www.juce.com/juce-privacy-policy
  15
  16    Or: You may also use this code under the terms of the GPL v3 (see
  17    www.gnu.org/licenses).
  18
  19    JUCE IS PROVIDED "AS IS" WITHOUT ANY WARRANTY, AND ALL WARRANTIES, WHETHER
  20    EXPRESSED OR IMPLIED, INCLUDING MERCHANTABILITY AND FITNESS FOR PURPOSE, ARE
  21    DISCLAIMED.
  22
  23   ==============================================================================
  24 */
  25
  26 namespace juce
  27 {
  28
  29 //==============================================================================
  30 /**
  31     A base class for top-level windows.
  32
  33     This class is used for components that are considered a major part of your
  34     application - e.g. ResizableWindow, DocumentWindow, DialogWindow, AlertWindow,
  35     etc. Things like menus that pop up briefly aren't derived from it.
  36
  37     A TopLevelWindow is probably on the desktop, but this isn't mandatory - it
  38     could itself be the child of another component.
  39
  40     The class manages a list of all instances of top-level windows that are in use,
  41     and each one is also given the concept of being "active". The active window is
  42     one that is actively being used by the user. This isn't quite the same as the
  43     component with the keyboard focus, because there may be a popup menu or other
  44     temporary window which gets keyboard focus while the active top level window is
  45     unchanged.
  46
  47     A top-level window also has an optional drop-shadow.
  48
  49     @see ResizableWindow, DocumentWindow, DialogWindow
  50
  51     @tags{GUI}
  52 */
  53 class JUCE_API  TopLevelWindow  : public Component
  54 {
  55 public:
  56     //==============================================================================
  57     /** Creates a TopLevelWindow.
  58
  59         @param name                 the name to give the component
  60         @param addToDesktop         if true, the window will be automatically added to the
  61                                     desktop; if false, you can use it as a child component
  62     */
  63     TopLevelWindow (const String& name, bool addToDesktop);
  64
  65     /** Destructor. */
  66     ~TopLevelWindow() override;
  67
  68     //==============================================================================
  69     /** True if this is currently the TopLevelWindow that is actively being used.
  70
  71         This isn't quite the same as having keyboard focus, because the focus may be
  72         on a child component or a temporary pop-up menu, etc, while this window is
  73         still considered to be active.
  74
  75         @see activeWindowStatusChanged
  76     */
  77     bool isActiveWindow() const noexcept                    { return isCurrentlyActive; }
  78
  79     //==============================================================================
  80     /** This will set the bounds of the window so that it's centred in front of another
  81         window.
  82
  83         If your app has a few windows open and want to pop up a dialog box for one of
  84         them, you can use this to show it in front of the relevant parent window, which
  85         is a bit neater than just having it appear in the middle of the screen.
  86
  87         If componentToCentreAround is nullptr, then the currently active TopLevelWindow will
  88         be used instead. If no window is focused, it'll just default to the middle of the
  89         screen.
  90     */
  91     void centreAroundComponent (Component* componentToCentreAround,
  92                                 int width, int height);
  93
  94     //==============================================================================
  95     /** Turns the drop-shadow on and off. */
  96     void setDropShadowEnabled (bool useShadow);
  97
  98     /** True if drop-shadowing is enabled. */
  99     bool isDropShadowEnabled() const noexcept               { return useDropShadow; }
 100
 101     /** Sets whether an OS-native title bar will be used, or a JUCE one.
 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         @see setUsingNativeTitleBar
 108     */
 109     bool isUsingNativeTitleBar() const noexcept;
 110
 111     //==============================================================================
 112     /** Returns the number of TopLevelWindow objects currently in use.
 113         @see getTopLevelWindow
 114     */
 115     static int getNumTopLevelWindows() noexcept;
 116
 117     /** Returns one of the TopLevelWindow objects currently in use.
 118         The index is 0 to (getNumTopLevelWindows() - 1).
 119     */
 120     static TopLevelWindow* getTopLevelWindow (int index) noexcept;
 121
 122     /** Returns the currently-active top level window.
 123         There might not be one, of course, so this can return nullptr.
 124     */
 125     static TopLevelWindow* getActiveTopLevelWindow() noexcept;
 126
 127     /** Adds the window to the desktop using the default flags. */
 128     void addToDesktop();
 129
 130     //==============================================================================
 131     /** @internal */
 132     void addToDesktop (int windowStyleFlags, void* nativeWindowToAttachTo = nullptr) override;
 133
 134 protected:
 135     //==============================================================================
 136     /** This callback happens when this window becomes active or inactive.
 137         @see isActiveWindow
 138     */
 139     virtual void activeWindowStatusChanged();
 140
 141
 142     //==============================================================================
 143     /** @internal */
 144     void focusOfChildComponentChanged (FocusChangeType) override;
 145     /** @internal */
 146     void parentHierarchyChanged() override;
 147     /** @internal */
 148     virtual int getDesktopWindowStyleFlags() const;
 149     /** @internal */
 150     void recreateDesktopWindow();
 151     /** @internal */
 152     void visibilityChanged() override;
 153
 154 private:
 155     friend class TopLevelWindowManager;
 156     friend class ResizableWindow;
 157     bool useDropShadow = true, useNativeTitleBar = true, isCurrentlyActive = false;
 158     std::unique_ptr<DropShadower> shadower;
 159
 160     std::unique_ptr<AccessibilityHandler> createAccessibilityHandler() override;
 161     void setWindowActive (bool);
 162
 163     JUCE_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR (TopLevelWindow)
 164 };
 165
 166 } // namespace juce