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