|
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263 |
- /*
- ==============================================================================
-
- This file is part of the JUCE library.
- Copyright (c) 2013 - Raw Material Software Ltd.
-
- Permission is granted to use this software under the terms of either:
- a) the GPL v2 (or any later version)
- b) the Affero GPL v3
-
- Details of these licenses can be found at: www.gnu.org/licenses
-
- JUCE is distributed in the hope that it will be useful, but WITHOUT ANY
- WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
- A PARTICULAR PURPOSE. See the GNU General Public License for more details.
-
- ------------------------------------------------------------------------------
-
- To release a closed-source product which uses JUCE, commercial licenses are
- available: visit www.juce.com for more information.
-
- ==============================================================================
- */
-
- #ifndef JUCE_DIALOGWINDOW_H_INCLUDED
- #define JUCE_DIALOGWINDOW_H_INCLUDED
-
-
- //==============================================================================
- /**
- A dialog-box style window.
-
- This class is a convenient way of creating a DocumentWindow with a close button
- that can be triggered by pressing the escape key.
-
- Any of the methods available to a DocumentWindow or ResizableWindow are also
- available to this, so it can be made resizable, have a menu bar, etc.
-
- You can either override or use an instance of the DialogWindow class directly,
- or you can use a DialogWindow::LaunchOptions structure to quickly set up and
- launch a box containing a content component.
-
- If you use the class directly, you'll need to override the
- DocumentWindow::closeButtonPressed() method to handle the user clicking the close
- button - for more info, see the DocumentWindow help.
-
- @see DocumentWindow, ResizableWindow
- */
- class JUCE_API DialogWindow : public DocumentWindow
- {
- public:
- //==============================================================================
- /** Creates a DialogWindow.
-
- @param name the name to give the component - this is also
- the title shown at the top of the window. To change
- this later, use setName()
- @param backgroundColour the colour to use for filling the window's background.
- @param escapeKeyTriggersCloseButton if true, then pressing the escape key will cause the
- close button to be triggered
- @param addToDesktop if true, the window will be automatically added to the
- desktop; if false, you can use it as a child component
- */
- DialogWindow (const String& name,
- Colour backgroundColour,
- bool escapeKeyTriggersCloseButton,
- bool addToDesktop = true);
-
- /** Destructor.
- If a content component has been set with setContentOwned(), it will be deleted.
- */
- ~DialogWindow();
-
- //==============================================================================
- /** This class defines a collection of settings to be used to open a DialogWindow.
-
- The easiest way to open a DialogWindow is to create yourself a LaunchOptions structure,
- initialise its fields with the appropriate details, and then call its launchAsync()
- method to launch the dialog.
- */
- struct LaunchOptions
- {
- LaunchOptions() noexcept;
-
- /** The title to give the window. */
- String dialogTitle;
-
- /** The background colour for the window. */
- Colour dialogBackgroundColour;
-
- /** The content component to show in the window. This must not be null!
- Using an OptionalScopedPointer to hold this pointer lets you indicate whether
- you'd like the dialog to automatically delete the component when the dialog
- has terminated.
- */
- OptionalScopedPointer <Component> content;
-
- /** If this is not a nullptr, it indicates a component that you'd like to position this
- dialog box in front of. See the DocumentWindow::centreAroundComponent() method for
- more info about this parameter.
- */
- Component* componentToCentreAround;
-
- /** If true, then the escape key will trigger the dialog's close button. */
- bool escapeKeyTriggersCloseButton;
- /** If true, the dialog will use a native title bar. See TopLevelWindow::setUsingNativeTitleBar() */
- bool useNativeTitleBar;
- /** If true, the window will be resizable. See ResizableWindow::setResizable() */
- bool resizable;
- /** Indicates whether to use a border or corner resizer component. See ResizableWindow::setResizable() */
- bool useBottomRightCornerResizer;
-
- /** Launches a new modal dialog window.
- This will create a dialog based on the settings in this structure,
- launch it modally, and return immediately. The window that is returned
- will be automatically deleted when the modal state is terminated.
-
- When the dialog's close button is clicked, it'll automatically terminate its
- modal state, but you can also do this programmatically by calling
- exitModalState (returnValue) on the DialogWindow.
-
- If your content component needs to find the dialog window that it is
- contained in, a quick trick is to do this:
- @code
- Dialogwindow* dw = contentComponent->findParentComponentOfClass<DialogWindow>();
-
- if (dw != nullptr)
- dw->exitModalState (1234);
- @endcode
- */
- DialogWindow* launchAsync();
-
- /** Creates a new DialogWindow instance with these settings.
- This method simply creates the window, it doesn't run it modally. In most cases
- you'll want to use launchAsync() or runModal() instead.
- */
- DialogWindow* create();
-
- #if JUCE_MODAL_LOOPS_PERMITTED || DOXYGEN
- /** Launches and runs the dialog modally, returning the status code that was
- used to terminate the modal loop.
-
- Note that running modal loops inline is a BAD technique. If possible, always
- use launchAsync() instead of this method.
- */
- int runModal();
- #endif
- };
-
- //==============================================================================
- /** Easy way of quickly showing a dialog box containing a given component.
-
- Note: this method has been superceded by the DialogWindow::LaunchOptions structure,
- which does the same job with some extra flexibility. The showDialog method is here
- for backwards compatibility, but please use DialogWindow::LaunchOptions in new code.
-
- This will open and display a DialogWindow containing a given component, making it
- modal, but returning immediately to allow the dialog to finish in its own time. If
- you want to block and run a modal loop until the dialog is dismissed, use showModalDialog()
- instead.
-
- To close the dialog programmatically, you should call exitModalState (returnValue) on
- the DialogWindow that is created. To find a pointer to this window from your
- contentComponent, you can do something like this:
- @code
- Dialogwindow* dw = contentComponent->findParentComponentOfClass<DialogWindow>();
-
- if (dw != nullptr)
- dw->exitModalState (1234);
- @endcode
-
- @param dialogTitle the dialog box's title
- @param contentComponent the content component for the dialog box. Make sure
- that this has been set to the size you want it to
- be before calling this method. The component won't
- be deleted by this call, so you can re-use it or delete
- it afterwards
- @param componentToCentreAround if this is non-zero, it indicates a component that
- you'd like to show this dialog box in front of. See the
- DocumentWindow::centreAroundComponent() method for more
- info on this parameter
- @param backgroundColour a colour to use for the dialog box's background colour
- @param escapeKeyTriggersCloseButton if true, then pressing the escape key will cause the
- close button to be triggered
- @param shouldBeResizable if true, the dialog window has either a resizable border, or
- a corner resizer
- @param useBottomRightCornerResizer if shouldBeResizable is true, this indicates whether
- to use a border or corner resizer component. See ResizableWindow::setResizable()
- */
- static void showDialog (const String& dialogTitle,
- Component* contentComponent,
- Component* componentToCentreAround,
- Colour backgroundColour,
- bool escapeKeyTriggersCloseButton,
- bool shouldBeResizable = false,
- bool useBottomRightCornerResizer = false,
- bool useNativeTitleBar = false);
-
- #if JUCE_MODAL_LOOPS_PERMITTED || DOXYGEN
- /** Easy way of quickly showing a dialog box containing a given component.
-
- Note: this method has been superceded by the DialogWindow::LaunchOptions structure,
- which does the same job with some extra flexibility. The showDialog method is here
- for backwards compatibility, but please use DialogWindow::LaunchOptions in new code.
-
- This will open and display a DialogWindow containing a given component, returning
- when the user clicks its close button.
-
- It returns the value that was returned by the dialog box's runModalLoop() call.
-
- To close the dialog programmatically, you should call exitModalState (returnValue) on
- the DialogWindow that is created. To find a pointer to this window from your
- contentComponent, you can do something like this:
- @code
- Dialogwindow* dw = contentComponent->findParentComponentOfClass<DialogWindow>();
-
- if (dw != nullptr)
- dw->exitModalState (1234);
- @endcode
-
- @param dialogTitle the dialog box's title
- @param contentComponent the content component for the dialog box. Make sure
- that this has been set to the size you want it to
- be before calling this method. The component won't
- be deleted by this call, so you can re-use it or delete
- it afterwards
- @param componentToCentreAround if this is non-zero, it indicates a component that
- you'd like to show this dialog box in front of. See the
- DocumentWindow::centreAroundComponent() method for more
- info on this parameter
- @param backgroundColour a colour to use for the dialog box's background colour
- @param escapeKeyTriggersCloseButton if true, then pressing the escape key will cause the
- close button to be triggered
- @param shouldBeResizable if true, the dialog window has either a resizable border, or
- a corner resizer
- @param useBottomRightCornerResizer if shouldBeResizable is true, this indicates whether
- to use a border or corner resizer component. See ResizableWindow::setResizable()
- */
- static int showModalDialog (const String& dialogTitle,
- Component* contentComponent,
- Component* componentToCentreAround,
- Colour backgroundColour,
- bool escapeKeyTriggersCloseButton,
- bool shouldBeResizable = false,
- bool useBottomRightCornerResizer = false,
- bool useNativeTitleBar = false);
- #endif
-
-
- protected:
- //==============================================================================
- /** @internal */
- void resized() override;
- /** @internal */
- bool keyPressed (const KeyPress&) override;
-
- private:
- bool escapeKeyTriggersCloseButton;
-
- JUCE_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR (DialogWindow)
- };
-
- #endif // JUCE_DIALOGWINDOW_H_INCLUDED
|