interface/wx/accel.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        accel.h
   3 // Purpose:     interface of wxAccelerator* classes
   4 // Author:      wxWidgets team
   5 // Licence:     wxWindows licence
   6 /////////////////////////////////////////////////////////////////////////////
   7
   8
   9 /** wxAcceleratorEntry flags */
  10 enum wxAcceleratorEntryFlags
  11 {
  12     /** no modifiers */
  13     wxACCEL_NORMAL,
  14
  15     /** hold Alt key down */
  16     wxACCEL_ALT,
  17
  18     /** hold Ctrl key down, corresponds to Command key on OS X */
  19     wxACCEL_CTRL,
  20
  21     /** hold Shift key down */
  22     wxACCEL_SHIFT,
  23
  24     /** corresponds to real Ctrl key on OS X, identic to @c wxACCEL_CTRL on other platforms */
  25     wxACCEL_RAW_CTRL,
  26
  27     /** deprecated, identic to @c wxACCEL_CTRL on all platforms. */
  28     wxACCEL_CMD
  29 };
  30
  31
  32 /**
  33     @class wxAcceleratorEntry
  34
  35     An object used by an application wishing to create an accelerator table
  36     (see wxAcceleratorTable).
  37
  38     @library{wxcore}
  39     @category{data}
  40
  41     @see wxAcceleratorTable, wxWindow::SetAcceleratorTable
  42 */
  43 class wxAcceleratorEntry
  44 {
  45 public:
  46     /**
  47         Constructor.
  48
  49         @param flags
  50             A combination of the ::wxAcceleratorEntryFlags values, which
  51             indicates which modifier keys are held down.
  52         @param keyCode
  53             The keycode to be detected. See ::wxKeyCode for a full list of keycodes.
  54         @param cmd
  55             The menu or control command identifier (ID).
  56         @param item
  57             The menu item associated with this accelerator.
  58     */
  59     wxAcceleratorEntry(int flags = 0, int keyCode = 0, int cmd = 0,
  60                        wxMenuItem *item = NULL);
  61
  62     /**
  63         Copy ctor.
  64     */
  65     wxAcceleratorEntry(const wxAcceleratorEntry& entry);
  66
  67     /**
  68         Returns the command identifier for the accelerator table entry.
  69     */
  70     int GetCommand() const;
  71
  72     /**
  73         Returns the flags for the accelerator table entry.
  74     */
  75     int GetFlags() const;
  76
  77     /**
  78         Returns the keycode for the accelerator table entry.
  79     */
  80     int GetKeyCode() const;
  81
  82     /**
  83         Returns the menu item associated with this accelerator entry.
  84     */
  85     wxMenuItem *GetMenuItem() const;
  86
  87     /**
  88         Sets the accelerator entry parameters.
  89
  90         @param flags
  91             A combination of the ::wxAcceleratorEntryFlags values, which
  92             indicates which modifier keys are held down.
  93         @param keyCode
  94             The keycode to be detected. See ::wxKeyCode for a full list of keycodes.
  95         @param cmd
  96             The menu or control command identifier (ID).
  97         @param item
  98             The menu item associated with this accelerator.
  99     */
 100     void Set(int flags, int keyCode, int cmd, wxMenuItem *item = NULL);
 101
 102     /**
 103         Returns @true if this object is correctly initialized.
 104     */
 105     bool IsOk() const;
 106
 107     /**
 108         Returns a textual representation of this accelerator.
 109
 110         The returned string is of the form <code>[Alt+][Ctrl+][RawCtrl+][Shift+]Key</code>
 111         where the modifier keys are present only if the corresponding flag is
 112         set.
 113     */
 114     wxString ToString() const;
 115
 116     /**
 117         Returns a textual representation of this accelerator which is
 118         appropriate for saving in configuration files.
 119
 120         Unlike the string returned by ToString(), this one is never translated
 121         so, while it's not suitable for showing to the user, it can be used to
 122         uniquely identify the accelerator independently of the user language.
 123
 124         The returned string can still be parsed by FromString().
 125
 126         @since 2.9.4
 127     */
 128     wxString ToRawString() const;
 129
 130     /**
 131         Parses the given string and sets the accelerator accordingly.
 132
 133         @param str
 134             This string may be either in the same format as returned by
 135             ToString(), i.e. contain the accelerator itself only, or have the
 136             format of a full menu item text with i.e. <code>Label TAB
 137             Accelerator</code>. In the latter case, the part of the string
 138             before the TAB is ignored. Notice that the latter format is only
 139             supported for the compatibility with the previous wxWidgets
 140             versions and the new code should pass only the accelerator string
 141             itself to this function.
 142
 143         @return @true if the given string correctly initialized this object
 144                 (i.e. if IsOk() returns true after this call)
 145     */
 146     bool FromString(const wxString& str);
 147
 148
 149     wxAcceleratorEntry& operator=(const wxAcceleratorEntry& entry);
 150     bool operator==(const wxAcceleratorEntry& entry) const;
 151     bool operator!=(const wxAcceleratorEntry& entry) const;
 152 };
 153
 154
 155 /**
 156     @class wxAcceleratorTable
 157
 158     An accelerator table allows the application to specify a table of keyboard
 159     shortcuts for menu or button commands.
 160
 161     The object ::wxNullAcceleratorTable is defined to be a table with no data, and
 162     is the initial accelerator table for a window.
 163
 164     Example:
 165
 166     @code
 167     wxAcceleratorEntry entries[4];
 168     entries[0].Set(wxACCEL_CTRL, (int) 'N', ID_NEW_WINDOW);
 169     entries[1].Set(wxACCEL_CTRL, (int) 'X', wxID_EXIT);
 170     entries[2].Set(wxACCEL_SHIFT, (int) 'A', ID_ABOUT);
 171     entries[3].Set(wxACCEL_NORMAL, WXK_DELETE, wxID_CUT);
 172
 173     wxAcceleratorTable accel(4, entries);
 174     frame->SetAcceleratorTable(accel);
 175     @endcode
 176
 177     @remarks
 178     An accelerator takes precedence over normal processing and can be a convenient
 179     way to program some event handling. For example, you can use an accelerator table
 180     to enable a dialog with a multi-line text control to accept CTRL-Enter as meaning
 181     'OK'.
 182
 183     @library{wxcore}
 184     @category{data}
 185
 186     @stdobjects
 187     ::wxNullAcceleratorTable
 188
 189     @see wxAcceleratorEntry, wxWindow::SetAcceleratorTable
 190 */
 191 class wxAcceleratorTable : public wxObject
 192 {
 193 public:
 194     /**
 195         Default ctor.
 196     */
 197     wxAcceleratorTable();
 198
 199     /**
 200         Initializes the accelerator table from an array of wxAcceleratorEntry.
 201
 202         @param n
 203             Number of accelerator entries.
 204         @param entries
 205             The array of entries.
 206
 207         @beginWxPerlOnly
 208         The wxPerl constructor accepts a list of either
 209         Wx::AcceleratorEntry objects or references to 3-element arrays
 210         [flags, keyCode, cmd] , like the parameters of
 211         Wx::AcceleratorEntry::new.
 212         @endWxPerlOnly
 213     */
 214     wxAcceleratorTable(int n, const wxAcceleratorEntry entries[]);
 215
 216     /**
 217         Loads the accelerator table from a Windows resource (Windows only).
 218
 219         @onlyfor{wxmsw}
 220
 221         @param resource
 222             Name of a Windows accelerator.
 223     */
 224     wxAcceleratorTable(const wxString& resource);
 225
 226     /**
 227         Destroys the wxAcceleratorTable object.
 228         See @ref overview_refcount_destruct for more info.
 229     */
 230     virtual ~wxAcceleratorTable();
 231
 232     /**
 233         Returns @true if the accelerator table is valid.
 234     */
 235     bool IsOk() const;
 236 };
 237
 238
 239 // ============================================================================
 240 // Global functions/macros
 241 // ============================================================================
 242
 243 /**
 244     An empty accelerator table.
 245 */
 246 wxAcceleratorTable wxNullAcceleratorTable;