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