juce_ComboBox.h

Go to the documentation of this file.

/*
  ==============================================================================
 
   This file is part of the JUCE library.
   Copyright (c) 2015 - ROLI 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_COMBOBOX_H_INCLUDED
#define JUCE_COMBOBOX_H_INCLUDED
 
 
//==============================================================================
class JUCE_API  ComboBox  : public Component,
                            public SettableTooltipClient,
                            public LabelListener,  // (can't use Label::Listener due to idiotic VC2005 bug)
                            public ValueListener,
                            private AsyncUpdater
{
public:
    //==============================================================================
    explicit ComboBox (const String& componentName = String::empty);
 
    ~ComboBox();
 
    //==============================================================================
    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; }
 
    virtual void addItemsToMenu (PopupMenu&) const;
 
    //==============================================================================
    class JUCE_API  Listener
    {
    public:
        virtual ~Listener() {}
 
        virtual void comboBoxChanged (ComboBox* comboBoxThatHasChanged) = 0;
    };
 
    void addListener (Listener* listener);
 
    void removeListener (Listener* listener);
 
    //==============================================================================
    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,    
    };
 
    //==============================================================================
    struct JUCE_API  LookAndFeelMethods
    {
        virtual ~LookAndFeelMethods() {}
 
        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;
    };
 
    //==============================================================================
    void labelTextChanged (Label*) override;
    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;
 
    // These methods' bool parameters have changed: see their new method signatures.
    JUCE_DEPRECATED (void clear (bool));
    JUCE_DEPRECATED (void setSelectedId (int, bool));
    JUCE_DEPRECATED (void setSelectedItemIndex (int, bool));
    JUCE_DEPRECATED (void setText (const String&, bool));
 
private:
    //==============================================================================
    struct ItemInfo
    {
        ItemInfo (const String&, int itemId, bool isEnabled, bool isHeading);
        bool isSeparator() const noexcept;
        bool isRealItem() const noexcept;
 
        String name;
        int itemId;
        bool isEnabled : 1, isHeading : 1;
    };
 
    OwnedArray<ItemInfo> items;
    Value currentId;
    int lastCurrentId;
    bool isButtonDown, separatorPending, menuActive, scrollWheelEnabled;
    float mouseWheelAccumulator;
    ListenerList<Listener> listeners;
    ScopedPointer<Label> label;
    String textWhenNothingSelected, noChoicesMessage;
 
    ItemInfo* getItemForId (int) const noexcept;
    ItemInfo* 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)
};
 
typedef ComboBox::Listener ComboBoxListener;
 
#endif   // JUCE_COMBOBOX_H_INCLUDED