interface/wx/accel.h

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