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 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
  33     An object used by an application wishing to create an accelerator table
  34     (see wxAcceleratorTable).
  35
  36     @library{wxcore}
  37     @category{misc}
  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 @ref page_keycodes 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 @ref page_keycodes 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 wxString for this accelerator.
 107         This function formats it using the @c "flags-keycode" format
 108         where @c flags maybe a hyphen-separed list of @c "shift|alt|ctrl".
 109     */
 110     wxString ToString() const;
 111
 112     /**
 113         Parses the given string and sets the accelerator accordingly.
 114
 115         @param str
 116             Should be a string in the form "flags-keycode"
 117
 118         @return @true if the given string correctly initialized this object
 119                 (i.e. if IsOk() returns true after this call)
 120     */
 121     bool FromString(const wxString& str);
 122
 123
 124     wxAcceleratorEntry& operator=(const wxAcceleratorEntry& entry);
 125     bool operator==(const wxAcceleratorEntry& entry) const;
 126     bool operator!=(const wxAcceleratorEntry& entry) const;
 127 };
 128
 129
 130 /**
 131     @class wxAcceleratorTable
 132
 133     An accelerator table allows the application to specify a table of keyboard
 134     shortcuts for menu or button commands.
 135
 136     The object ::wxNullAcceleratorTable is defined to be a table with no data, and
 137     is the initial accelerator table for a window.
 138
 139     Example:
 140
 141     @code
 142     wxAcceleratorEntry entries[4];
 143     entries[0].Set(wxACCEL_CTRL, (int) 'N', ID_NEW_WINDOW);
 144     entries[1].Set(wxACCEL_CTRL, (int) 'X', wxID_EXIT);
 145     entries[2].Set(wxACCEL_SHIFT, (int) 'A', ID_ABOUT);
 146     entries[3].Set(wxACCEL_NORMAL, WXK_DELETE, wxID_CUT);
 147
 148     wxAcceleratorTable accel(4, entries);
 149     frame->SetAcceleratorTable(accel);
 150     @endcode
 151
 152     @remarks
 153     An accelerator takes precedence over normal processing and can be a convenient
 154     way to program some event handling. For example, you can use an accelerator table
 155     to enable a dialog with a multi-line text control to accept CTRL-Enter as meaning
 156     'OK'.
 157
 158     @library{wxcore}
 159     @category{misc}
 160
 161     @stdobjects
 162     ::wxNullAcceleratorTable
 163
 164     @see wxAcceleratorEntry, wxWindow::SetAcceleratorTable
 165 */
 166 class wxAcceleratorTable : public wxObject
 167 {
 168 public:
 169     /**
 170         Default ctor.
 171     */
 172     wxAcceleratorTable();
 173
 174     /**
 175         Initializes the accelerator table from an array of wxAcceleratorEntry.
 176
 177         @param n
 178             Number of accelerator entries.
 179         @param entries
 180             The array of entries.
 181     */
 182     wxAcceleratorTable(int n, const wxAcceleratorEntry entries[]);
 183
 184     /**
 185         Loads the accelerator table from a Windows resource (Windows only).
 186
 187         @onlyfor{wxmsw}
 188
 189         @param resource
 190             Name of a Windows accelerator.
 191     */
 192     wxAcceleratorTable(const wxString& resource);
 193
 194     /**
 195         Destroys the wxAcceleratorTable object.
 196         See @ref overview_refcount_destruct for more info.
 197     */
 198     virtual ~wxAcceleratorTable();
 199
 200     /**
 201         Returns @true if the accelerator table is valid.
 202     */
 203     bool IsOk() const;
 204 };
 205
 206
 207 // ============================================================================
 208 // Global functions/macros
 209 // ============================================================================
 210
 211 /**
 212     An empty accelerator table.
 213 */
 214 wxAcceleratorTable wxNullAcceleratorTable;