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