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 base class for a component that goes in a PropertyPanel and displays one of
32     an item's properties.
33 
34     Subclasses of this are used to display a property in various forms, e.g. a
35     ChoicePropertyComponent shows its value as a combo box; a SliderPropertyComponent
36     shows its value as a slider; a TextPropertyComponent as a text box, etc.
37 
38     A subclass must implement the refresh() method which will be called to tell the
39     component to update itself, and is also responsible for calling this it when the
40     item that it refers to is changed.
41 
42     @see PropertyPanel, TextPropertyComponent, SliderPropertyComponent,
43          ChoicePropertyComponent, ButtonPropertyComponent, BooleanPropertyComponent
44 
45     @tags{GUI}
46 */
47 class JUCE_API  PropertyComponent  : public Component,
48                                      public SettableTooltipClient
49 {
50 public:
51     //==============================================================================
52     /** Creates a PropertyComponent.
53 
54         @param propertyName     the name is stored as this component's name, and is
55                                 used as the name displayed next to this component in
56                                 a property panel
57         @param preferredHeight  the height that the component should be given - some
58                                 items may need to be larger than a normal row height.
59                                 This value can also be set if a subclass changes the
60                                 preferredHeight member variable.
61     */
62     PropertyComponent (const String& propertyName,
63                        int preferredHeight = 25);
64 
65     /** Destructor. */
66     ~PropertyComponent() override;
67 
68     //==============================================================================
69     /** Returns this item's preferred height.
70 
71         This value is specified either in the constructor or by a subclass changing the
72         preferredHeight member variable.
73     */
getPreferredHeight()74     int getPreferredHeight() const noexcept                 { return preferredHeight; }
75 
setPreferredHeight(int newHeight)76     void setPreferredHeight (int newHeight) noexcept        { preferredHeight = newHeight; }
77 
78     //==============================================================================
79     /** Updates the property component if the item it refers to has changed.
80 
81         A subclass must implement this method, and other objects may call it to
82         force it to refresh itself.
83 
84         The subclass should be economical in the amount of work is done, so for
85         example it should check whether it really needs to do a repaint rather than
86         just doing one every time this method is called, as it may be called when
87         the value being displayed hasn't actually changed.
88     */
89     virtual void refresh() = 0;
90 
91 
92     /** The default paint method fills the background and draws a label for the
93         item's name.
94 
95         @see LookAndFeel::drawPropertyComponentBackground(), LookAndFeel::drawPropertyComponentLabel()
96     */
97     void paint (Graphics&) override;
98 
99     /** The default resize method positions any child component to the right of this
100         one, based on the look and feel's default label size.
101     */
102     void resized() override;
103 
104     /** By default, this just repaints the component. */
105     void enablementChanged() override;
106 
107     //==============================================================================
108     /** A set of colour IDs to use to change the colour of various aspects of the combo box.
109 
110         These constants can be used either via the Component::setColour(), or LookAndFeel::setColour()
111         methods.
112 
113         @see Component::setColour, Component::findColour, LookAndFeel::setColour, LookAndFeel::findColour
114     */
115     enum ColourIds
116     {
117         backgroundColourId     = 0x1008300,    /**< The background colour to fill the component with. */
118         labelTextColourId      = 0x1008301,    /**< The colour for the property's label text. */
119     };
120 
121     //==============================================================================
122     /** This abstract base class is implemented by LookAndFeel classes. */
123     struct JUCE_API  LookAndFeelMethods
124     {
125         virtual ~LookAndFeelMethods() = default;
126 
127         virtual void drawPropertyPanelSectionHeader (Graphics&, const String& name, bool isOpen, int width, int height) = 0;
128         virtual void drawPropertyComponentBackground (Graphics&, int width, int height, PropertyComponent&) = 0;
129         virtual void drawPropertyComponentLabel (Graphics&, int width, int height, PropertyComponent&) = 0;
130         virtual Rectangle<int> getPropertyComponentContentPosition (PropertyComponent&) = 0;
131         virtual int getPropertyPanelSectionHeaderHeight (const String& sectionTitle) = 0;
132     };
133 
134 protected:
135     /** Used by the PropertyPanel to determine how high this component needs to be.
136         A subclass can update this value in its constructor but shouldn't alter it later
137         as changes won't necessarily be picked up.
138     */
139     int preferredHeight;
140 
141 private:
142     JUCE_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR (PropertyComponent)
143 };
144 
145 } // namespace juce
146