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 component to allow editing of the keymaps stored by a KeyPressMappingSet
32     object.
33 
34     @see KeyPressMappingSet
35 
36     @tags{GUI}
37 */
38 class JUCE_API  KeyMappingEditorComponent  : public Component
39 {
40 public:
41     //==============================================================================
42     /** Creates a KeyMappingEditorComponent.
43 
44         @param mappingSet   this is the set of mappings to display and edit. Make sure the
45                             mappings object is not deleted before this component!
46         @param showResetToDefaultButton     if true, then at the bottom of the list, the
47                                             component will include a 'reset to defaults' button.
48     */
49     KeyMappingEditorComponent (KeyPressMappingSet& mappingSet,
50                                bool showResetToDefaultButton);
51 
52     /** Destructor. */
53     ~KeyMappingEditorComponent() override;
54 
55     //==============================================================================
56     /** Sets up the colours to use for parts of the component.
57 
58         @param mainBackground       colour to use for most of the background
59         @param textColour           colour to use for the text
60     */
61     void setColours (Colour mainBackground,
62                      Colour textColour);
63 
64     /** Returns the KeyPressMappingSet that this component is acting upon. */
getMappings()65     KeyPressMappingSet& getMappings() const noexcept                { return mappings; }
66 
67     /** Returns the ApplicationCommandManager that this component is connected to. */
getCommandManager()68     ApplicationCommandManager& getCommandManager() const noexcept   { return mappings.getCommandManager(); }
69 
70 
71     //==============================================================================
72     /** Can be overridden if some commands need to be excluded from the list.
73 
74         By default this will use the KeyPressMappingSet's shouldCommandBeVisibleInEditor()
75         method to decide what to return, but you can override it to handle special cases.
76     */
77     virtual bool shouldCommandBeIncluded (CommandID commandID);
78 
79     /** Can be overridden to indicate that some commands are shown as read-only.
80 
81         By default this will use the KeyPressMappingSet's shouldCommandBeReadOnlyInEditor()
82         method to decide what to return, but you can override it to handle special cases.
83     */
84     virtual bool isCommandReadOnly (CommandID commandID);
85 
86     /** This can be overridden to let you change the format of the string used
87         to describe a keypress.
88 
89         This is handy if you're using non-standard KeyPress objects, e.g. for custom
90         keys that are triggered by something else externally. If you override the
91         method, be sure to let the base class's method handle keys you're not
92         interested in.
93     */
94     virtual String getDescriptionForKeyPress (const KeyPress& key);
95 
96     //==============================================================================
97     /** A set of colour IDs to use to change the colour of various aspects of the editor.
98 
99         These constants can be used either via the Component::setColour(), or LookAndFeel::setColour()
100         methods.
101 
102         @see Component::setColour, Component::findColour, LookAndFeel::setColour, LookAndFeel::findColour
103     */
104     enum ColourIds
105     {
106         backgroundColourId  = 0x100ad00,    /**< The background colour to fill the editor background. */
107         textColourId        = 0x100ad01,    /**< The colour for the text. */
108     };
109 
110     //==============================================================================
111     /** @internal */
112     void parentHierarchyChanged() override;
113     /** @internal */
114     void resized() override;
115 
116 private:
117     //==============================================================================
118     KeyPressMappingSet& mappings;
119     TreeView tree;
120     TextButton resetButton;
121 
122     class TopLevelItem;
123     class ChangeKeyButton;
124     class MappingItem;
125     class CategoryItem;
126     class ItemComponent;
127     std::unique_ptr<TopLevelItem> treeItem;
128 
129     JUCE_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR (KeyMappingEditorComponent)
130 };
131 
132 } // namespace juce
133