interface/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     @wxheader{accel.h}
  33
  34     An object used by an application wishing to create an accelerator table
  35     (see wxAcceleratorTable).
  36
  37     @library{wxcore}
  38     @category{misc}
  39
  40     @see wxAcceleratorTable, wxWindow::SetAcceleratorTable
  41 */
  42 class wxAcceleratorEntry
  43 {
  44 public:
  45     /**
  46         Constructor.
  47
  48         @param flags
  49             A combination of the wxAcceleratorEntryFlags values, which
  50             indicates which modifier keys are held down.
  51         @param keyCode
  52             The keycode to be detected. See @ref page_keycodes for a full list of keycodes.
  53         @param cmd
  54             The menu or control command identifier (ID).
  55         @param item
  56             The menu item associated with this accelerator.
  57     */
  58     wxAcceleratorEntry(int flags = 0, int keyCode = 0, int cmd = 0,
  59                        wxMenuItem *item = NULL);
  60
  61     /**
  62         Copy ctor.
  63     */
  64     wxAcceleratorEntry(const wxAcceleratorEntry& entry);
  65
  66     /**
  67         Returns the command identifier for the accelerator table entry.
  68     */
  69     int GetCommand() const;
  70
  71     /**
  72         Returns the flags for the accelerator table entry.
  73     */
  74     int GetFlags() const;
  75
  76     /**
  77         Returns the keycode for the accelerator table entry.
  78     */
  79     int GetKeyCode() const;
  80
  81     /**
  82         Returns the menu item associated with this accelerator entry.
  83     */
  84     wxMenuItem *GetMenuItem() const;
  85
  86     /**
  87         Sets the accelerator entry parameters.
  88
  89         @param flags
  90             A combination of the wxAcceleratorEntryFlags values, which
  91             indicates which modifier keys are held down.
  92         @param keyCode
  93             The keycode to be detected. See @ref page_keycodes for a full list of keycodes.
  94         @param cmd
  95             The menu or control command identifier (ID).
  96         @param item
  97             The menu item associated with this accelerator.
  98     */
  99     void Set(int flags, int keyCode, int cmd, wxMenuItem *item = NULL);
 100
 101     /**
 102         Returns @true if this object is correctly initialized.
 103     */
 104     bool IsOk() const;
 105
 106     /**
 107         Returns a wxString for this accelerator.
 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     @wxheader{accel.h}
 134
 135     An accelerator table allows the application to specify a table of keyboard
 136     shortcuts for menu or button commands.
 137
 138     The object ::wxNullAcceleratorTable is defined to be a table with no data, and
 139     is the initial accelerator table for a window.
 140
 141     Example:
 142
 143     @code
 144     wxAcceleratorEntry entries[4];
 145     entries[0].Set(wxACCEL_CTRL, (int) 'N', ID_NEW_WINDOW);
 146     entries[1].Set(wxACCEL_CTRL, (int) 'X', wxID_EXIT);
 147     entries[2].Set(wxACCEL_SHIFT, (int) 'A', ID_ABOUT);
 148     entries[3].Set(wxACCEL_NORMAL, WXK_DELETE, wxID_CUT);
 149
 150     wxAcceleratorTable accel(4, entries);
 151     frame->SetAcceleratorTable(accel);
 152     @endcode
 153
 154     @remarks
 155     An accelerator takes precedence over normal processing and can be a convenient
 156     way to program some event handling. For example, you can use an accelerator table
 157     to enable a dialog with a multi-line text control to accept CTRL-Enter as meaning
 158     'OK'.
 159
 160     @library{wxcore}
 161     @category{misc}
 162
 163     @stdobjects
 164     ::wxNullAcceleratorTable
 165
 166     @see wxAcceleratorEntry, wxWindow::SetAcceleratorTable
 167 */
 168 class wxAcceleratorTable : public wxObject
 169 {
 170 public:
 171     /**
 172         Default ctor.
 173     */
 174     wxAcceleratorTable();
 175
 176     /**
 177         Initializes the accelerator table from an array of wxAcceleratorEntry.
 178
 179         @param n
 180             Number of accelerator entries.
 181         @param entries
 182             The array of entries.
 183     */
 184     wxAcceleratorTable(int n, const wxAcceleratorEntry entries[]);
 185
 186     /**
 187         Loads the accelerator table from a Windows resource (Windows only).
 188
 189         @onlyfor{wxmsw}
 190
 191         @param resource
 192             Name of a Windows accelerator.
 193     */
 194     wxAcceleratorTable(const wxString& resource);
 195
 196     /**
 197         Destroys the wxAcceleratorTable object.
 198         See @ref overview_refcount_destruct for more info.
 199     */
 200     virtual ~wxAcceleratorTable();
 201
 202     /**
 203         Returns @true if the accelerator table is valid.
 204     */
 205     bool IsOk() const;
 206 };
 207
 208
 209 // ============================================================================
 210 // Global functions/macros
 211 // ============================================================================
 212
 213 /**
 214     An empty accelerator table.
 215 */
 216 wxAcceleratorTable wxNullAcceleratorTable;