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 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
        };
 
        //==============================================================================
        JUCE_NODISCARD Options withTargetComponent (Component* targetComponent) const;
        JUCE_NODISCARD Options withTargetComponent (Component& targetComponent) const;

        JUCE_NODISCARD Options withTargetScreenArea (Rectangle<int> targetArea) const;

        JUCE_NODISCARD Options withMousePosition() const;

        JUCE_NODISCARD Options withDeletionCheck (Component& componentToWatchForDeletion) const;

        JUCE_NODISCARD Options withMinimumWidth (int minWidth) const;

        JUCE_NODISCARD Options withMinimumNumColumns (int minNumColumns) const;

        JUCE_NODISCARD Options withMaximumNumColumns (int maxNumColumns) const;

        JUCE_NODISCARD Options withStandardItemHeight (int standardHeight) const;

        JUCE_NODISCARD Options withItemThatMustBeVisible (int idOfItemToBeVisible) const;

        JUCE_NODISCARD Options withParentComponent (Component* parentComponent) const;

        JUCE_NODISCARD Options withPreferredPopupDirection (PopupDirection direction) const;

        JUCE_NODISCARD Options withInitiallySelectedItem (int idOfItemToBeSelected) const;
 
        //==============================================================================
        Component* getParentComponent() const noexcept               { return parentComponent; }

        Component* getTargetComponent() const noexcept               { return targetComponent; }

        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;
        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