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 licence
   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 textual representation of this accelerator.
 107
 108         The returned string is of the form <code>[Alt+][Ctrl+][Shift+]Key</code>
 109         where the modifier keys are present only if the corresponding flag is
 110         set.
 111     */
 112     wxString ToString() const;
 113
 114     /**
 115         Parses the given string and sets the accelerator accordingly.
 116
 117         @param str
 118             This string may be either in the same format as returned by
 119             ToString(), i.e. contain the accelerator itself only, or have the
 120             format of a full menu item text with i.e. <code>Label TAB
 121             Accelerator</code>. In the latter case, the part of the string
 122             before the TAB is ignored.
 123
 124         @return @true if the given string correctly initialized this object
 125                 (i.e. if IsOk() returns true after this call)
 126     */
 127     bool FromString(const wxString& str);
 128
 129
 130     wxAcceleratorEntry& operator=(const wxAcceleratorEntry& entry);
 131     bool operator==(const wxAcceleratorEntry& entry) const;
 132     bool operator!=(const wxAcceleratorEntry& entry) const;
 133 };
 134
 135
 136 /**
 137     @class wxAcceleratorTable
 138
 139     An accelerator table allows the application to specify a table of keyboard
 140     shortcuts for menu or button commands.
 141
 142     The object ::wxNullAcceleratorTable is defined to be a table with no data, and
 143     is the initial accelerator table for a window.
 144
 145     Example:
 146
 147     @code
 148     wxAcceleratorEntry entries[4];
 149     entries[0].Set(wxACCEL_CTRL, (int) 'N', ID_NEW_WINDOW);
 150     entries[1].Set(wxACCEL_CTRL, (int) 'X', wxID_EXIT);
 151     entries[2].Set(wxACCEL_SHIFT, (int) 'A', ID_ABOUT);
 152     entries[3].Set(wxACCEL_NORMAL, WXK_DELETE, wxID_CUT);
 153
 154     wxAcceleratorTable accel(4, entries);
 155     frame->SetAcceleratorTable(accel);
 156     @endcode
 157
 158     @remarks
 159     An accelerator takes precedence over normal processing and can be a convenient
 160     way to program some event handling. For example, you can use an accelerator table
 161     to enable a dialog with a multi-line text control to accept CTRL-Enter as meaning
 162     'OK'.
 163
 164     @library{wxcore}
 165     @category{data}
 166
 167     @stdobjects
 168     ::wxNullAcceleratorTable
 169
 170     @see wxAcceleratorEntry, wxWindow::SetAcceleratorTable
 171 */
 172 class wxAcceleratorTable : public wxObject
 173 {
 174 public:
 175     /**
 176         Default ctor.
 177     */
 178     wxAcceleratorTable();
 179
 180     /**
 181         Initializes the accelerator table from an array of wxAcceleratorEntry.
 182
 183         @param n
 184             Number of accelerator entries.
 185         @param entries
 186             The array of entries.
 187
 188         @beginWxPerlOnly
 189         The wxPerl constructor accepts a list of either
 190         Wx::AcceleratorEntry objects or references to 3-element arrays
 191         [flags, keyCode, cmd] , like the parameters of
 192         Wx::AcceleratorEntry::new.
 193         @endWxPerlOnly
 194     */
 195     wxAcceleratorTable(int n, const wxAcceleratorEntry entries[]);
 196
 197     /**
 198         Loads the accelerator table from a Windows resource (Windows only).
 199
 200         @onlyfor{wxmsw}
 201
 202         @param resource
 203             Name of a Windows accelerator.
 204     */
 205     wxAcceleratorTable(const wxString& resource);
 206
 207     /**
 208         Destroys the wxAcceleratorTable object.
 209         See @ref overview_refcount_destruct for more info.
 210     */
 211     virtual ~wxAcceleratorTable();
 212
 213     /**
 214         Returns @true if the accelerator table is valid.
 215     */
 216     bool IsOk() const;
 217 };
 218
 219
 220 // ============================================================================
 221 // Global functions/macros
 222 // ============================================================================
 223
 224 /**
 225     An empty accelerator table.
 226 */
 227 wxAcceleratorTable wxNullAcceleratorTable;