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     Holds information describing an application command.
32 
33     This object is used to pass information about a particular command, such as its
34     name, description and other usage flags.
35 
36     When an ApplicationCommandTarget is asked to provide information about the commands
37     it can perform, this is the structure gets filled-in to describe each one.
38 
39     @see ApplicationCommandTarget, ApplicationCommandTarget::getCommandInfo(),
40          ApplicationCommandManager
41 
42     @tags{GUI}
43 */
44 struct JUCE_API  ApplicationCommandInfo
45 {
46     //==============================================================================
47     explicit ApplicationCommandInfo (CommandID commandID) noexcept;
48 
49     //==============================================================================
50     /** Sets a number of the structures values at once.
51 
52         The meanings of each of the parameters is described below, in the appropriate
53         member variable's description.
54     */
55     void setInfo (const String& shortName,
56                   const String& description,
57                   const String& categoryName,
58                   int flags) noexcept;
59 
60     /** An easy way to set or remove the isDisabled bit in the structure's flags field.
61 
62         If isActive is true, the flags member has the isDisabled bit cleared; if isActive
63         is false, the bit is set.
64     */
65     void setActive (bool isActive) noexcept;
66 
67     /** An easy way to set or remove the isTicked bit in the structure's flags field.
68     */
69     void setTicked (bool isTicked) noexcept;
70 
71     /** Handy method for adding a keypress to the defaultKeypresses array.
72 
73         This is just so you can write things like:
74         @code
75         myinfo.addDefaultKeypress ('s', ModifierKeys::commandModifier);
76         @endcode
77         instead of
78         @code
79         myinfo.defaultKeypresses.add (KeyPress ('s', ModifierKeys::commandModifier));
80         @endcode
81     */
82     void addDefaultKeypress (int keyCode, ModifierKeys modifiers) noexcept;
83 
84     //==============================================================================
85     /** The command's unique ID number.
86     */
87     CommandID commandID;
88 
89     /** A short name to describe the command.
90 
91         This should be suitable for use in menus, on buttons that trigger the command, etc.
92 
93         You can use the setInfo() method to quickly set this and some of the command's
94         other properties.
95     */
96     String shortName;
97 
98     /** A longer description of the command.
99 
100         This should be suitable for use in contexts such as a KeyMappingEditorComponent or
101         pop-up tooltip describing what the command does.
102 
103         You can use the setInfo() method to quickly set this and some of the command's
104         other properties.
105     */
106     String description;
107 
108     /** A named category that the command fits into.
109 
110         You can give your commands any category you like, and these will be displayed in
111         contexts such as the KeyMappingEditorComponent, where the category is used to group
112         commands together.
113 
114         You can use the setInfo() method to quickly set this and some of the command's
115         other properties.
116     */
117     String categoryName;
118 
119     /** A list of zero or more keypresses that should be used as the default keys for
120         this command.
121 
122         Methods such as KeyPressMappingSet::resetToDefaultMappings() will use the keypresses in
123         this list to initialise the default set of key-to-command mappings.
124 
125         @see addDefaultKeypress
126     */
127     Array<KeyPress> defaultKeypresses;
128 
129     //==============================================================================
130     /** Flags describing the ways in which this command should be used.
131 
132         A bitwise-OR of these values is stored in the ApplicationCommandInfo::flags
133         variable.
134     */
135     enum CommandFlags
136     {
137         /** Indicates that the command can't currently be performed.
138 
139             The ApplicationCommandTarget::getCommandInfo() method must set this flag if it's
140             not currently permissible to perform the command. If the flag is set, then
141             components that trigger the command, e.g. PopupMenu, may choose to grey-out the
142             command or show themselves as not being enabled.
143 
144             @see ApplicationCommandInfo::setActive
145         */
146         isDisabled                  = 1 << 0,
147 
148         /** Indicates that the command should have a tick next to it on a menu.
149 
150             If your command is shown on a menu and this is set, it'll show a tick next to
151             it. Other components such as buttons may also use this flag to indicate that it
152             is a value that can be toggled, and is currently in the 'on' state.
153 
154             @see ApplicationCommandInfo::setTicked
155         */
156         isTicked                    = 1 << 1,
157 
158         /** If this flag is present, then when a KeyPressMappingSet invokes the command,
159             it will call the command twice, once on key-down and again on key-up.
160 
161             @see ApplicationCommandTarget::InvocationInfo
162         */
163         wantsKeyUpDownCallbacks     = 1 << 2,
164 
165         /** If this flag is present, then a KeyMappingEditorComponent will not display the
166             command in its list.
167         */
168         hiddenFromKeyEditor         = 1 << 3,
169 
170         /** If this flag is present, then a KeyMappingEditorComponent will display the
171             command in its list, but won't allow the assigned keypress to be changed.
172         */
173         readOnlyInKeyEditor         = 1 << 4,
174 
175         /** If this flag is present and the command is invoked from a keypress, then any
176             buttons or menus that are also connected to the command will not flash to
177             indicate that they've been triggered.
178         */
179         dontTriggerVisualFeedback   = 1 << 5
180     };
181 
182     /** A bitwise-OR of the values specified in the CommandFlags enum.
183 
184         You can use the setInfo() method to quickly set this and some of the command's
185         other properties.
186     */
187     int flags;
188 };
189 
190 } // namespace juce
191