juce/source/src/application/juce_ApplicationCommandInfo.h

   1 /*
   2   ==============================================================================
   3
   4    This file is part of the JUCE library - "Jules' Utility Class Extensions"
   5    Copyright 2004-11 by Raw Material Software Ltd.
   6
   7   ------------------------------------------------------------------------------
   8
   9    JUCE can be redistributed and/or modified under the terms of the GNU General
  10    Public License (Version 2), as published by the Free Software Foundation.
  11    A copy of the license is included in the JUCE distribution, or can be found
  12    online at www.gnu.org/licenses.
  13
  14    JUCE is distributed in the hope that it will be useful, but WITHOUT ANY
  15    WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
  16    A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
  17
  18   ------------------------------------------------------------------------------
  19
  20    To release a closed-source product which uses JUCE, commercial licenses are
  21    available: visit www.rawmaterialsoftware.com/juce for more information.
  22
  23   ==============================================================================
  24 */
  25
  26 #ifndef __JUCE_APPLICATIONCOMMANDINFO_JUCEHEADER__
  27 #define __JUCE_APPLICATIONCOMMANDINFO_JUCEHEADER__
  28
  29 #include "../text/juce_String.h"
  30 #include "../containers/juce_Array.h"
  31 #include "../gui/components/keyboard/juce_KeyPress.h"
  32 #include "juce_ApplicationCommandID.h"
  33
  34
  35 //==============================================================================
  36 /**
  37     Holds information describing an application command.
  38
  39     This object is used to pass information about a particular command, such as its
  40     name, description and other usage flags.
  41
  42     When an ApplicationCommandTarget is asked to provide information about the commands
  43     it can perform, this is the structure gets filled-in to describe each one.
  44
  45     @see ApplicationCommandTarget, ApplicationCommandTarget::getCommandInfo(),
  46          ApplicationCommandManager
  47 */
  48 struct JUCE_API  ApplicationCommandInfo
  49 {
  50     //==============================================================================
  51     explicit ApplicationCommandInfo (CommandID commandID) noexcept;
  52
  53     //==============================================================================
  54     /** Sets a number of the structures values at once.
  55
  56         The meanings of each of the parameters is described below, in the appropriate
  57         member variable's description.
  58     */
  59     void setInfo (const String& shortName,
  60                   const String& description,
  61                   const String& categoryName,
  62                   int flags) noexcept;
  63
  64     /** An easy way to set or remove the isDisabled bit in the structure's flags field.
  65
  66         If isActive is true, the flags member has the isDisabled bit cleared; if isActive
  67         is false, the bit is set.
  68     */
  69     void setActive (bool isActive) noexcept;
  70
  71     /** An easy way to set or remove the isTicked bit in the structure's flags field.
  72     */
  73     void setTicked (bool isTicked) noexcept;
  74
  75     /** Handy method for adding a keypress to the defaultKeypresses array.
  76
  77         This is just so you can write things like:
  78         @code
  79         myinfo.addDefaultKeypress ('s', ModifierKeys::commandModifier);
  80         @endcode
  81         instead of
  82         @code
  83         myinfo.defaultKeypresses.add (KeyPress ('s', ModifierKeys::commandModifier));
  84         @endcode
  85     */
  86     void addDefaultKeypress (int keyCode,
  87                              const ModifierKeys& modifiers) noexcept;
  88
  89     //==============================================================================
  90     /** The command's unique ID number.
  91     */
  92     CommandID commandID;
  93
  94     /** A short name to describe the command.
  95
  96         This should be suitable for use in menus, on buttons that trigger the command, etc.
  97
  98         You can use the setInfo() method to quickly set this and some of the command's
  99         other properties.
 100     */
 101     String shortName;
 102
 103     /** A longer description of the command.
 104
 105         This should be suitable for use in contexts such as a KeyMappingEditorComponent or
 106         pop-up tooltip describing what the command does.
 107
 108         You can use the setInfo() method to quickly set this and some of the command's
 109         other properties.
 110     */
 111     String description;
 112
 113     /** A named category that the command fits into.
 114
 115         You can give your commands any category you like, and these will be displayed in
 116         contexts such as the KeyMappingEditorComponent, where the category is used to group
 117         commands together.
 118
 119         You can use the setInfo() method to quickly set this and some of the command's
 120         other properties.
 121     */
 122     String categoryName;
 123
 124     /** A list of zero or more keypresses that should be used as the default keys for
 125         this command.
 126
 127         Methods such as KeyPressMappingSet::resetToDefaultMappings() will use the keypresses in
 128         this list to initialise the default set of key-to-command mappings.
 129
 130         @see addDefaultKeypress
 131     */
 132     Array <KeyPress> defaultKeypresses;
 133
 134     //==============================================================================
 135     /** Flags describing the ways in which this command should be used.
 136
 137         A bitwise-OR of these values is stored in the ApplicationCommandInfo::flags
 138         variable.
 139     */
 140     enum CommandFlags
 141     {
 142         /** Indicates that the command can't currently be performed.
 143
 144             The ApplicationCommandTarget::getCommandInfo() method must set this flag if it's
 145             not currently permissable to perform the command. If the flag is set, then
 146             components that trigger the command, e.g. PopupMenu, may choose to grey-out the
 147             command or show themselves as not being enabled.
 148
 149             @see ApplicationCommandInfo::setActive
 150         */
 151         isDisabled                  = 1 << 0,
 152
 153         /** Indicates that the command should have a tick next to it on a menu.
 154
 155             If your command is shown on a menu and this is set, it'll show a tick next to
 156             it. Other components such as buttons may also use this flag to indicate that it
 157             is a value that can be toggled, and is currently in the 'on' state.
 158
 159             @see ApplicationCommandInfo::setTicked
 160         */
 161         isTicked                    = 1 << 1,
 162
 163         /** If this flag is present, then when a KeyPressMappingSet invokes the command,
 164             it will call the command twice, once on key-down and again on key-up.
 165
 166             @see ApplicationCommandTarget::InvocationInfo
 167         */
 168         wantsKeyUpDownCallbacks     = 1 << 2,
 169
 170         /** If this flag is present, then a KeyMappingEditorComponent will not display the
 171             command in its list.
 172         */
 173         hiddenFromKeyEditor         = 1 << 3,
 174
 175         /** If this flag is present, then a KeyMappingEditorComponent will display the
 176             command in its list, but won't allow the assigned keypress to be changed.
 177         */
 178         readOnlyInKeyEditor         = 1 << 4,
 179
 180         /** If this flag is present and the command is invoked from a keypress, then any
 181             buttons or menus that are also connected to the command will not flash to
 182             indicate that they've been triggered.
 183         */
 184         dontTriggerVisualFeedback   = 1 << 5
 185     };
 186
 187     /** A bitwise-OR of the values specified in the CommandFlags enum.
 188
 189         You can use the setInfo() method to quickly set this and some of the command's
 190         other properties.
 191     */
 192     int flags;
 193 };
 194
 195
 196 #endif   // __JUCE_APPLICATIONCOMMANDINFO_JUCEHEADER__