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