juce_ComboBox.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  ComboBox  : public Component,
                            public SettableTooltipClient,
                            public Value::Listener,
                            private AsyncUpdater
{
public:
    //==============================================================================
    explicit ComboBox (const String& componentName = {});

    ~ComboBox() override;
 
    //==============================================================================
    void setEditableText (bool isEditable);

    bool isTextEditable() const noexcept;

    void setJustificationType (Justification justification);

    Justification getJustificationType() const noexcept;
 
    //==============================================================================
    void addItem (const String& newItemText, int newItemId);

    void addItemList (const StringArray& items, int firstItemIdOffset);

    void addSeparator();

    void addSectionHeading (const String& headingName);

    void setItemEnabled (int itemId, bool shouldBeEnabled);

    bool isItemEnabled (int itemId) const noexcept;

    void changeItemText (int itemId, const String& newText);

    void clear (NotificationType notification = sendNotificationAsync);

    int getNumItems() const noexcept;

    String getItemText (int index) const;

    int getItemId (int index) const noexcept;

    int indexOfItemId (int itemId) const noexcept;
 
    //==============================================================================
    int getSelectedId() const noexcept;

    Value& getSelectedIdAsValue()                       { return currentId; }

    void setSelectedId (int newItemId,
                        NotificationType notification = sendNotificationAsync);
 
    //==============================================================================
    int getSelectedItemIndex() const;

    void setSelectedItemIndex (int newItemIndex,
                               NotificationType notification = sendNotificationAsync);
 
    //==============================================================================
    String getText() const;

    void setText (const String& newText,
                  NotificationType notification = sendNotificationAsync);

    void showEditor();

    virtual void showPopup();

    void hidePopup();

    bool isPopupActive() const noexcept                 { return menuActive; }

    PopupMenu* getRootMenu() noexcept { return &currentMenu; }

    const PopupMenu* getRootMenu() const noexcept { return &currentMenu; }
 
    //==============================================================================
    class JUCE_API  Listener
    {
    public:
        virtual ~Listener() = default;

        virtual void comboBoxChanged (ComboBox* comboBoxThatHasChanged) = 0;
    };

    void addListener (Listener* listener);

    void removeListener (Listener* listener);
 
    //==============================================================================
    std::function<void()> onChange;
 
    //==============================================================================
    void setTextWhenNothingSelected (const String& newMessage);

    String getTextWhenNothingSelected() const;

    void setTextWhenNoChoicesAvailable (const String& newMessage);

    String getTextWhenNoChoicesAvailable() const;
 
    //==============================================================================
    void setTooltip (const String& newTooltip) override;

    void setScrollWheelEnabled (bool enabled) noexcept;
 
 
    //==============================================================================
    enum ColourIds
    {
        backgroundColourId     = 0x1000b00,   
        textColourId           = 0x1000a00,   
        outlineColourId        = 0x1000c00,   
        buttonColourId         = 0x1000d00,   
        arrowColourId          = 0x1000e00,   
        focusedOutlineColourId = 0x1000f00    
    };
 
    //==============================================================================
    struct JUCE_API  LookAndFeelMethods
    {
        virtual ~LookAndFeelMethods() = default;
 
        virtual void drawComboBox (Graphics&, int width, int height, bool isButtonDown,
                                   int buttonX, int buttonY, int buttonW, int buttonH,
                                   ComboBox&) = 0;
 
        virtual Font getComboBoxFont (ComboBox&) = 0;
 
        virtual Label* createComboBoxTextBox (ComboBox&) = 0;
 
        virtual void positionComboBoxText (ComboBox&, Label& labelToPosition) = 0;
 
        virtual PopupMenu::Options getOptionsForComboBoxPopupMenu (ComboBox&, Label&) = 0;
 
        virtual void drawComboBoxTextWhenNothingSelected (Graphics&, ComboBox&, Label&) = 0;
    };
 
    //==============================================================================
    void enablementChanged() override;
    void colourChanged() override;
    void focusGained (Component::FocusChangeType) override;
    void focusLost (Component::FocusChangeType) override;
    void handleAsyncUpdate() override;
    String getTooltip() override                        { return label->getTooltip(); }
    void mouseDown (const MouseEvent&) override;
    void mouseDrag (const MouseEvent&) override;
    void mouseUp (const MouseEvent&) override;
    void mouseWheelMove (const MouseEvent&, const MouseWheelDetails&) override;
    void lookAndFeelChanged() override;
    void paint (Graphics&) override;
    void resized() override;
    bool keyStateChanged (bool) override;
    bool keyPressed (const KeyPress&) override;
    void valueChanged (Value&) override;
    void parentHierarchyChanged() override;
 
    //==============================================================================
   #ifndef DOXYGEN
    // These methods' bool parameters have changed: see their new method signatures.
    [[deprecated]] void clear (bool);
    [[deprecated]] void setSelectedId (int, bool);
    [[deprecated]] void setSelectedItemIndex (int, bool);
    [[deprecated]] void setText (const String&, bool);
   #endif
 
private:
    //==============================================================================
    enum EditableState
    {
        editableUnknown,
        labelIsNotEditable,
        labelIsEditable
    };
 
    PopupMenu currentMenu;
    Value currentId;
    int lastCurrentId = 0;
    bool isButtonDown = false, menuActive = false, scrollWheelEnabled = false;
    float mouseWheelAccumulator = 0;
    ListenerList<Listener> listeners;
    std::unique_ptr<Label> label;
    String textWhenNothingSelected, noChoicesMessage;
    EditableState labelEditableState = editableUnknown;
 
    std::unique_ptr<AccessibilityHandler> createAccessibilityHandler() override;
    PopupMenu::Item* getItemForId (int) const noexcept;
    PopupMenu::Item* getItemForIndex (int) const noexcept;
    bool selectIfEnabled (int index);
    bool nudgeSelectedItem (int delta);
    void sendChange (NotificationType);
    void showPopupIfNotActive();
 
    JUCE_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR (ComboBox)
};
 
 
} // namespace juce