juce_PopupMenu.h

Go to the documentation of this file.

 /*
  ==============================================================================
 
   This file is part of the JUCE library.
   Copyright (c) 2022 - Raw Material Software Limited
 
   JUCE is an open source library subject to commercial or open-source
   licensing.
 
   By using JUCE, you agree to the terms of both the JUCE 7 End-User License
   Agreement and JUCE Privacy Policy.
 
   End User License Agreement: www.juce.com/juce-7-licence
   Privacy Policy: www.juce.com/juce-privacy-policy
 
   Or: You may also use this code under the terms of the GPL v3 (see
   www.gnu.org/licenses).
 
   JUCE IS PROVIDED "AS IS" WITHOUT ANY WARRANTY, AND ALL WARRANTIES, WHETHER
   EXPRESSED OR IMPLIED, INCLUDING MERCHANTABILITY AND FITNESS FOR PURPOSE, ARE
   DISCLAIMED.
 
  ==============================================================================
*/
 
namespace juce
{
 
//==============================================================================
class JUCE_API  PopupMenu
{
public:
    //==============================================================================
    PopupMenu() = default;
 
    PopupMenu (const PopupMenu&);
 
    ~PopupMenu();
 
    PopupMenu& operator= (const PopupMenu&);
 
    PopupMenu (PopupMenu&&) noexcept;
 
    PopupMenu& operator= (PopupMenu&&) noexcept;
 
    //==============================================================================
    class CustomComponent;
    class CustomCallback;
 
    //==============================================================================
    void clear();
 
    struct JUCE_API  Item
    {
        Item();
 
        Item (String text);
 
        Item (const Item&);
        Item& operator= (const Item&);
        Item (Item&&);
        Item& operator= (Item&&);
 
        String text;
 
        int itemID = 0;
 
        std::function<void()> action;
 
        std::unique_ptr<PopupMenu> subMenu;
 
        std::unique_ptr<Drawable> image;
 
        ReferenceCountedObjectPtr<CustomComponent> customComponent;
 
        ReferenceCountedObjectPtr<CustomCallback> customCallback;
 
        ApplicationCommandManager* commandManager = nullptr;
 
        String shortcutKeyDescription;
 
        Colour colour;
 
        bool isEnabled = true;
 
        bool isTicked = false;
 
        bool isSeparator = false;
 
        bool isSectionHeader = false;
 
        bool shouldBreakAfter = false;
 
        Item& setTicked (bool shouldBeTicked = true) & noexcept;
        Item& setEnabled (bool shouldBeEnabled) & noexcept;
        Item& setAction (std::function<void()> action) & noexcept;
        Item& setID (int newID) & noexcept;
        Item& setColour (Colour) & noexcept;
        Item& setCustomComponent (ReferenceCountedObjectPtr<CustomComponent> customComponent) & noexcept;
        Item& setImage (std::unique_ptr<Drawable>) & noexcept;
 
        Item&& setTicked (bool shouldBeTicked = true) && noexcept;
        Item&& setEnabled (bool shouldBeEnabled) && noexcept;
        Item&& setAction (std::function<void()> action) && noexcept;
        Item&& setID (int newID) && noexcept;
        Item&& setColour (Colour) && noexcept;
        Item&& setCustomComponent (ReferenceCountedObjectPtr<CustomComponent> customComponent) && noexcept;
        Item&& setImage (std::unique_ptr<Drawable>) && noexcept;
    };
 
    void addItem (Item newItem);
 
    void addItem (String itemText,
                  std::function<void()> action);
 
    void addItem (String itemText,
                  bool isEnabled,
                  bool isTicked,
                  std::function<void()> action);
 
    void addItem (int itemResultID,
                  String itemText,
                  bool isEnabled = true,
                  bool isTicked = false);
 
    void addItem (int itemResultID,
                  String itemText,
                  bool isEnabled,
                  bool isTicked,
                  const Image& iconToUse);
 
    void addItem (int itemResultID,
                  String itemText,
                  bool isEnabled,
                  bool isTicked,
                  std::unique_ptr<Drawable> iconToUse);
 
    void addCommandItem (ApplicationCommandManager* commandManager,
                         CommandID commandID,
                         String displayName,
                         std::unique_ptr<Drawable> iconToUse);
 
    void addCommandItem (ApplicationCommandManager* commandManager,
                         CommandID commandID,
                         String displayName = {});
 
    void addColouredItem (int itemResultID,
                          String itemText,
                          Colour itemTextColour,
                          bool isEnabled = true,
                          bool isTicked = false,
                          const Image& iconToUse = {});
 
    void addColouredItem (int itemResultID,
                          String itemText,
                          Colour itemTextColour,
                          bool isEnabled,
                          bool isTicked,
                          std::unique_ptr<Drawable> iconToUse);
 
    void addCustomItem (int itemResultID,
                        std::unique_ptr<CustomComponent> customComponent,
                        std::unique_ptr<const PopupMenu> optionalSubMenu = nullptr,
                        const String& itemTitle = {});
 
    void addCustomItem (int itemResultID,
                        Component& customComponent,
                        int idealWidth,
                        int idealHeight,
                        bool triggerMenuItemAutomaticallyWhenClicked,
                        std::unique_ptr<const PopupMenu> optionalSubMenu = nullptr,
                        const String& itemTitle = {});
 
    void addSubMenu (String subMenuName,
                     PopupMenu subMenu,
                     bool isEnabled = true);
 
    void addSubMenu (String subMenuName,
                     PopupMenu subMenu,
                     bool isEnabled,
                     const Image& iconToUse,
                     bool isTicked = false,
                     int itemResultID = 0);
 
    void addSubMenu (String subMenuName,
                     PopupMenu subMenu,
                     bool isEnabled,
                     std::unique_ptr<Drawable> iconToUse,
                     bool isTicked = false,
                     int itemResultID = 0);
 
    void addSeparator();
 
    void addSectionHeader (String title);
 
    void addColumnBreak();
 
    int getNumItems() const noexcept;
 
    bool containsCommandItem (int commandID) const;
 
    bool containsAnyActiveItems() const noexcept;
 
    //==============================================================================
    class JUCE_API  Options
    {
    public:
        Options();
 
        Options (const Options&) = default;
        Options& operator= (const Options&) = default;
 
        enum class PopupDirection
        {
            upwards,
            downwards
        };
 
        //==============================================================================
        [[nodiscard]] Options withTargetComponent (Component* targetComponent) const;
        [[nodiscard]] Options withTargetComponent (Component& targetComponent) const;
 
        [[nodiscard]] Options withTargetScreenArea (Rectangle<int> targetArea) const;
 
        [[nodiscard]] Options withMousePosition() const;
 
        [[nodiscard]] Options withDeletionCheck (Component& componentToWatchForDeletion) const;
 
        [[nodiscard]] Options withMinimumWidth (int minWidth) const;
 
        [[nodiscard]] Options withMinimumNumColumns (int minNumColumns) const;
 
        [[nodiscard]] Options withMaximumNumColumns (int maxNumColumns) const;
 
        [[nodiscard]] Options withStandardItemHeight (int standardHeight) const;
 
        [[nodiscard]] Options withItemThatMustBeVisible (int idOfItemToBeVisible) const;
 
        [[nodiscard]] Options withParentComponent (Component* parentComponent) const;
 
        [[nodiscard]] Options withPreferredPopupDirection (PopupDirection direction) const;
 
        [[nodiscard]] Options withInitiallySelectedItem (int idOfItemToBeSelected) const;
 
        [[nodiscard]] Options forSubmenu() const;
 
        //==============================================================================
        Component* getParentComponent() const noexcept               { return parentComponent; }
 
        Component* getTargetComponent() const noexcept               { return targetComponent; }
 
        Component* getTopLevelTargetComponent() const noexcept       { return topLevelTarget; }
 
        bool hasWatchedComponentBeenDeleted() const noexcept         { return isWatchingForDeletion && componentToWatchForDeletion == nullptr; }
 
        Rectangle<int> getTargetScreenArea() const noexcept          { return targetArea; }
 
        int getMinimumWidth() const noexcept                         { return minWidth; }
 
        int getMaximumNumColumns() const noexcept                    { return maxColumns; }
 
        int getMinimumNumColumns() const noexcept                    { return minColumns; }
 
        int getStandardItemHeight() const noexcept                   { return standardHeight; }
 
        int getItemThatMustBeVisible() const noexcept                { return visibleItemID; }
 
        PopupDirection getPreferredPopupDirection() const noexcept   { return preferredPopupDirection; }
 
        int getInitiallySelectedItemId() const noexcept              { return initiallySelectedItemId; }
 
    private:
        //==============================================================================
        Rectangle<int> targetArea;
        WeakReference<Component> targetComponent, parentComponent, componentToWatchForDeletion, topLevelTarget;
        int visibleItemID = 0, minWidth = 0, minColumns = 1, maxColumns = 0, standardHeight = 0, initiallySelectedItemId = 0;
        bool isWatchingForDeletion = false;
        PopupDirection preferredPopupDirection = PopupDirection::downwards;
    };
 
    //==============================================================================
   #if JUCE_MODAL_LOOPS_PERMITTED
    int show (int itemIDThatMustBeVisible = 0,
              int minimumWidth = 0,
              int maximumNumColumns = 0,
              int standardItemHeight = 0,
              ModalComponentManager::Callback* callback = nullptr);
 
 
    int showAt (Rectangle<int> screenAreaToAttachTo,
                int itemIDThatMustBeVisible = 0,
                int minimumWidth = 0,
                int maximumNumColumns = 0,
                int standardItemHeight = 0,
                ModalComponentManager::Callback* callback = nullptr);
 
    int showAt (Component* componentToAttachTo,
                int itemIDThatMustBeVisible = 0,
                int minimumWidth = 0,
                int maximumNumColumns = 0,
                int standardItemHeight = 0,
                ModalComponentManager::Callback* callback = nullptr);
 
    int showMenu (const Options& options);
   #endif
 
    void showMenuAsync (const Options& options);
 
    void showMenuAsync (const Options& options,
                        ModalComponentManager::Callback* callback);
 
    void showMenuAsync (const Options& options,
                        std::function<void (int)> callback);
 
    //==============================================================================
    static bool JUCE_CALLTYPE dismissAllActiveMenus();
 
 
    //==============================================================================
    void setLookAndFeel (LookAndFeel* newLookAndFeel);
 
    //==============================================================================
    enum ColourIds
    {
        backgroundColourId             = 0x1000700,  
        textColourId                   = 0x1000600,  
        headerTextColourId             = 0x1000601,  
        highlightedBackgroundColourId  = 0x1000900,  
        highlightedTextColourId        = 0x1000800,  
    };
 
    //==============================================================================
    class JUCE_API  MenuItemIterator
    {
    public:
        //==============================================================================
        MenuItemIterator (const PopupMenu& menu, bool searchRecursively = false);
 
        ~MenuItemIterator();
 
        bool next();
 
        Item& getItem() const;
 
    private:
        //==============================================================================
        bool searchRecursively;
 
        Array<int> index;
        Array<const PopupMenu*> menus;
        PopupMenu::Item* currentItem = nullptr;
 
        MenuItemIterator& operator= (const MenuItemIterator&);
        JUCE_LEAK_DETECTOR (MenuItemIterator)
    };
 
    //==============================================================================
    class JUCE_API  CustomComponent  : public Component,
                                       public SingleThreadedReferenceCountedObject
    {
    public:
        CustomComponent();
 
        explicit CustomComponent (bool isTriggeredAutomatically);
 
        virtual void getIdealSize (int& idealWidth, int& idealHeight) = 0;
 
        void triggerMenuItem();
 
        bool isItemHighlighted() const noexcept                 { return isHighlighted; }
 
        const PopupMenu::Item* getItem() const noexcept         { return item; }
 
        bool isTriggeredAutomatically() const noexcept          { return triggeredAutomatically; }
        void setHighlighted (bool shouldBeHighlighted);
 
    private:
        //==============================================================================
        bool isHighlighted = false, triggeredAutomatically;
        const PopupMenu::Item* item = nullptr;
 
        friend PopupMenu;
 
        JUCE_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR (CustomComponent)
    };
 
    //==============================================================================
    class JUCE_API  CustomCallback  : public SingleThreadedReferenceCountedObject
    {
    public:
        CustomCallback();
        ~CustomCallback() override;
 
        virtual bool menuItemTriggered() = 0;
 
    private:
        JUCE_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR (CustomCallback)
    };
 
    //==============================================================================
    struct JUCE_API  LookAndFeelMethods
    {
        virtual ~LookAndFeelMethods() = default;
 
        virtual void drawPopupMenuBackground (Graphics&, int width, int height);
 
        virtual void drawPopupMenuBackgroundWithOptions (Graphics&,
                                                         int width,
                                                         int height,
                                                         const Options&) = 0;
 
        virtual void drawPopupMenuItem (Graphics&, const Rectangle<int>& area,
                                        bool isSeparator, bool isActive, bool isHighlighted,
                                        bool isTicked, bool hasSubMenu,
                                        const String& text,
                                        const String& shortcutKeyText,
                                        const Drawable* icon,
                                        const Colour* textColour);
 
        virtual void drawPopupMenuItemWithOptions (Graphics&, const Rectangle<int>& area,
                                                   bool isHighlighted,
                                                   const Item& item,
                                                   const Options&) = 0;
 
        virtual void drawPopupMenuSectionHeader (Graphics&, const Rectangle<int>&,
                                                 const String&);
 
        virtual void drawPopupMenuSectionHeaderWithOptions (Graphics&, const Rectangle<int>& area,
                                                            const String& sectionName,
                                                            const Options&) = 0;
 
        virtual Font getPopupMenuFont() = 0;
 
        virtual void drawPopupMenuUpDownArrow (Graphics&,
                                               int width, int height,
                                               bool isScrollUpArrow);
 
        virtual void drawPopupMenuUpDownArrowWithOptions (Graphics&,
                                                          int width, int height,
                                                          bool isScrollUpArrow,
                                                          const Options&) = 0;
 
        virtual void getIdealPopupMenuItemSize (const String& text,
                                                bool isSeparator,
                                                int standardMenuItemHeight,
                                                int& idealWidth,
                                                int& idealHeight);
 
        virtual void getIdealPopupMenuItemSizeWithOptions (const String& text,
                                                           bool isSeparator,
                                                           int standardMenuItemHeight,
                                                           int& idealWidth,
                                                           int& idealHeight,
                                                           const Options&) = 0;
 
        virtual int getMenuWindowFlags() = 0;
 
        virtual void drawMenuBarBackground (Graphics&, int width, int height,
                                            bool isMouseOverBar,
                                            MenuBarComponent&) = 0;
 
        virtual int getDefaultMenuBarHeight() = 0;
 
        virtual int getMenuBarItemWidth (MenuBarComponent&, int itemIndex, const String& itemText) = 0;
 
        virtual Font getMenuBarFont (MenuBarComponent&, int itemIndex, const String& itemText) = 0;
 
        virtual void drawMenuBarItem (Graphics&, int width, int height,
                                      int itemIndex,
                                      const String& itemText,
                                      bool isMouseOverItem,
                                      bool isMenuOpen,
                                      bool isMouseOverBar,
                                      MenuBarComponent&) = 0;
 
        virtual Component* getParentComponentForMenuOptions (const Options& options) = 0;
 
        virtual void preparePopupMenuWindow (Component& newWindow) = 0;
 
        virtual bool shouldPopupMenuScaleWithTargetComponent (const Options& options) = 0;
 
        virtual int getPopupMenuBorderSize();
 
        virtual int getPopupMenuBorderSizeWithOptions (const Options&) = 0;
 
        virtual void drawPopupMenuColumnSeparatorWithOptions (Graphics& g,
                                                              const Rectangle<int>& bounds,
                                                              const Options&) = 0;
 
        virtual int getPopupMenuColumnSeparatorWidthWithOptions (const Options&) = 0;
    };
 
    //==============================================================================
   #ifndef DOXYGEN
    [[deprecated ("Use the new method.")]]
    int drawPopupMenuItem (Graphics&, int, int, bool, bool, bool, bool, bool, const String&, const String&, Image*, const Colour*) { return 0; }
   #endif
 
private:
    //==============================================================================
    JUCE_PUBLIC_IN_DLL_BUILD (struct HelperClasses)
    class Window;
    friend struct HelperClasses;
    friend class MenuBarComponent;
 
    Array<Item> items;
    WeakReference<LookAndFeel> lookAndFeel;
 
    Component* createWindow (const Options&, ApplicationCommandManager**) const;
    int showWithOptionalCallback (const Options&, ModalComponentManager::Callback*, bool);
 
    static void setItem (CustomComponent&, const Item*);
 
    JUCE_LEAK_DETECTOR (PopupMenu)
};
 
} // namespace juce