1 /* 2 ============================================================================== 3 4 This file is part of the JUCE library. 5 Copyright (c) 2020 - Raw Material Software Limited 6 7 JUCE is an open source library subject to commercial or open-source 8 licensing. 9 10 By using JUCE, you agree to the terms of both the JUCE 6 End-User License 11 Agreement and JUCE Privacy Policy (both effective as of the 16th June 2020). 12 13 End User License Agreement: www.juce.com/juce-6-licence 14 Privacy Policy: www.juce.com/juce-privacy-policy 15 16 Or: You may also use this code under the terms of the GPL v3 (see 17 www.gnu.org/licenses). 18 19 JUCE IS PROVIDED "AS IS" WITHOUT ANY WARRANTY, AND ALL WARRANTIES, WHETHER 20 EXPRESSED OR IMPLIED, INCLUDING MERCHANTABILITY AND FITNESS FOR PURPOSE, ARE 21 DISCLAIMED. 22 23 ============================================================================== 24 */ 25 26 namespace juce 27 { 28 29 //============================================================================== 30 /** 31 A PropertyComponent that shows its value as a combo box. 32 33 This type of property component contains a list of options and has a 34 combo box to choose one. 35 36 Your subclass's constructor must add some strings to the choices StringArray 37 and these are shown in the list. 38 39 The getIndex() method will be called to find out which option is the currently 40 selected one. If you call refresh() it will call getIndex() to check whether 41 the value has changed, and will update the combo box if needed. 42 43 If the user selects a different item from the list, setIndex() will be 44 called to let your class process this. 45 46 @see PropertyComponent, PropertyPanel 47 48 @tags{GUI} 49 */ 50 class JUCE_API ChoicePropertyComponent : public PropertyComponent 51 { 52 private: 53 /** Delegating constructor. */ 54 ChoicePropertyComponent (const String&, const StringArray&, const Array<var>&); 55 56 protected: 57 /** Creates the component. 58 Your subclass's constructor must add a list of options to the choices member variable. 59 */ 60 ChoicePropertyComponent (const String& propertyName); 61 62 public: 63 /** Creates the component. 64 65 Note that if you call this constructor then you must use the Value to interact with the 66 index, and you can't override the class with your own setIndex or getIndex methods. 67 If you want to use those methods, call the other constructor instead. 68 69 @param valueToControl the value that the combo box will read and control 70 @param propertyName the name of the property 71 @param choices the list of possible values that the drop-down list will contain 72 @param correspondingValues a list of values corresponding to each item in the 'choices' StringArray. 73 These are the values that will be read and written to the 74 valueToControl value. This array must contain the same number of items 75 as the choices array 76 */ 77 ChoicePropertyComponent (const Value& valueToControl, 78 const String& propertyName, 79 const StringArray& choices, 80 const Array<var>& correspondingValues); 81 82 /** Creates the component using a ValueWithDefault object. This will add an item to the ComboBox for the 83 default value with an ID of -1. 84 85 @param valueToControl the ValueWithDefault object that contains the Value object that the combo box will read and control. 86 @param propertyName the name of the property 87 @param choices the list of possible values that the drop-down list will contain 88 @param correspondingValues a list of values corresponding to each item in the 'choices' StringArray. 89 These are the values that will be read and written to the 90 valueToControl value. This array must contain the same number of items 91 as the choices array 92 93 */ 94 ChoicePropertyComponent (ValueWithDefault& valueToControl, 95 const String& propertyName, 96 const StringArray& choices, 97 const Array<var>& correspondingValues); 98 99 /** Creates the component using a ValueWithDefault object, adding an item to the ComboBox for the 100 default value with an ID of -1 as well as adding separate "Enabled" and "Disabled" options. 101 102 This is useful for simple on/off choices that also need a default value. 103 */ 104 ChoicePropertyComponent (ValueWithDefault& valueToControl, 105 const String& propertyName); 106 107 /** Destructor. */ 108 ~ChoicePropertyComponent() override; 109 110 //============================================================================== 111 /** Called when the user selects an item from the combo box. 112 113 Your subclass must use this callback to update the value that this component 114 represents. The index is the index of the chosen item in the choices 115 StringArray. 116 */ 117 virtual void setIndex (int newIndex); 118 119 /** Returns the index of the item that should currently be shown. 120 This is the index of the item in the choices StringArray that will be shown. 121 */ 122 virtual int getIndex() const; 123 124 /** Returns the list of options. */ 125 const StringArray& getChoices() const; 126 127 //============================================================================== 128 /** @internal */ 129 void refresh() override; 130 131 protected: 132 /** The list of options that will be shown in the combo box. 133 134 Your subclass must populate this array in its constructor. If any empty 135 strings are added, these will be replaced with horizontal separators (see 136 ComboBox::addSeparator() for more info). 137 */ 138 StringArray choices; 139 140 private: 141 //============================================================================== 142 class RemapperValueSource; 143 class RemapperValueSourceWithDefault; 144 145 //============================================================================== 146 void createComboBox(); 147 void createComboBoxWithDefault (const String&); 148 149 void changeIndex(); 150 151 //============================================================================== 152 ComboBox comboBox; 153 bool isCustomClass = false; 154 155 WeakReference<ValueWithDefault> valueWithDefault; 156 157 //============================================================================== 158 JUCE_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR (ChoicePropertyComponent) 159 }; 160 161 } // namespace juce 162