X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/23324ae1c7938ba904770fc456d3c07764b9c5e9..49d37022125686b42877f0a5a971e13fb1381e87:/interface/accel.h?ds=sidebyside diff --git a/interface/accel.h b/interface/accel.h index 5ae1b3f4e2..2763733330 100644 --- a/interface/accel.h +++ b/interface/accel.h @@ -1,140 +1,216 @@ ///////////////////////////////////////////////////////////////////////////// // Name: accel.h -// Purpose: documentation for wxAcceleratorEntry class +// Purpose: interface of wxAccelerator* classes // Author: wxWidgets team // RCS-ID: $Id$ // Licence: wxWindows license ///////////////////////////////////////////////////////////////////////////// + +/** wxAcceleratorEntry flags */ +enum wxAcceleratorEntryFlags +{ + /** no modifiers */ + wxACCEL_NORMAL, + + /** hold Alt key down */ + wxACCEL_ALT, + + /** hold Ctrl key down */ + wxACCEL_CTRL, + + /** hold Shift key down */ + wxACCEL_SHIFT, + + /** Command key on OS X; identic to wxACCEL_CTRL on other platforms. */ + wxACCEL_CMD +}; + + /** @class wxAcceleratorEntry @wxheader{accel.h} - - An object used by an application wishing to create an @ref - overview_wxacceleratortable "accelerator table". - + + An object used by an application wishing to create an accelerator table + (see wxAcceleratorTable). + @library{wxcore} - @category{FIXME} - - @seealso - wxAcceleratorTable, wxWindow::SetAcceleratorTable + @category{misc} + + @see wxAcceleratorTable, wxWindow::SetAcceleratorTable */ -class wxAcceleratorEntry +class wxAcceleratorEntry { public: - //@{ /** Constructor. - - @param flags - One of wxACCEL_ALT, wxACCEL_SHIFT, wxACCEL_CTRL and wxACCEL_NORMAL. Indicates - which modifier key is held down. - - @param keyCode - The keycode to be detected. See Keycodes for a full list of keycodes. - - @param cmd - The menu or control command identifier. + + @param flags + A combination of the wxAcceleratorEntryFlags values, which + indicates which modifier keys are held down. + @param keyCode + The keycode to be detected. See @ref page_keycodes for a full list of keycodes. + @param cmd + The menu or control command identifier (ID). + @param item + The menu item associated with this accelerator. + */ + wxAcceleratorEntry(int flags = 0, int keyCode = 0, int cmd = 0, + wxMenuItem *item = NULL); + + /** + Copy ctor. */ - wxAcceleratorEntry(); - wxAcceleratorEntry(int flags, int keyCode, int cmd); - //@} + wxAcceleratorEntry(const wxAcceleratorEntry& entry); /** Returns the command identifier for the accelerator table entry. */ - int GetCommand(); + int GetCommand() const; /** Returns the flags for the accelerator table entry. */ - int GetFlags(); + int GetFlags() const; /** Returns the keycode for the accelerator table entry. */ - int GetKeyCode(); + int GetKeyCode() const; + + /** + Returns the menu item associated with this accelerator entry. + */ + wxMenuItem *GetMenuItem() const; /** Sets the accelerator entry parameters. - - @param flags - One of wxACCEL_ALT, wxACCEL_SHIFT, wxACCEL_CTRL and wxACCEL_NORMAL. Indicates - which modifier key is held down. - - @param keyCode - The keycode to be detected. See Keycodes for a full list of keycodes. - - @param cmd - The menu or control command identifier. + + @param flags + A combination of the wxAcceleratorEntryFlags values, which + indicates which modifier keys are held down. + @param keyCode + The keycode to be detected. See @ref page_keycodes for a full list of keycodes. + @param cmd + The menu or control command identifier (ID). + @param item + The menu item associated with this accelerator. + */ + void Set(int flags, int keyCode, int cmd, wxMenuItem *item = NULL); + + /** + Returns @true if this object is correctly initialized. + */ + bool IsOk() const; + + /** + Returns a wxString for this accelerator. + This function formats it using the @c "flags-keycode" format + where @c flags maybe a hyphen-separed list of @c "shift|alt|ctrl". + */ + wxString ToString() const; + + /** + Parses the given string and sets the accelerator accordingly. + + @param str + Should be a string in the form "flags-keycode" + + @returns @true if the given string correctly initialized this object + (i.e. if IsOk() returns true after this call) */ -#define void Set(int flags, int keyCode, int cmd) /* implementation is private */ + bool FromString(const wxString& str); + + + wxAcceleratorEntry& operator=(const wxAcceleratorEntry& entry); + bool operator==(const wxAcceleratorEntry& entry) const; + bool operator!=(const wxAcceleratorEntry& entry) const; }; /** @class wxAcceleratorTable @wxheader{accel.h} - + An accelerator table allows the application to specify a table of keyboard - shortcuts for - menus or other commands. On Windows and Mac OS X, menu or button commands are - supported; on GTK, - only menu commands are supported. - - The object @b wxNullAcceleratorTable is defined to be a table with no data, and - is the - initial accelerator table for a window. - + shortcuts for menu or button commands. + + The object ::wxNullAcceleratorTable is defined to be a table with no data, and + is the initial accelerator table for a window. + + Example: + + @code + wxAcceleratorEntry entries[4]; + entries[0].Set(wxACCEL_CTRL, (int) 'N', ID_NEW_WINDOW); + entries[1].Set(wxACCEL_CTRL, (int) 'X', wxID_EXIT); + entries[2].Set(wxACCEL_SHIFT, (int) 'A', ID_ABOUT); + entries[3].Set(wxACCEL_NORMAL, WXK_DELETE, wxID_CUT); + + wxAcceleratorTable accel(4, entries); + frame->SetAcceleratorTable(accel); + @endcode + + @remarks + An accelerator takes precedence over normal processing and can be a convenient + way to program some event handling. For example, you can use an accelerator table + to enable a dialog with a multi-line text control to accept CTRL-Enter as meaning + 'OK'. + @library{wxcore} @category{misc} - + @stdobjects - Objects: - wxNullAcceleratorTable - - @seealso - wxAcceleratorEntry, wxWindow::SetAcceleratorTable + ::wxNullAcceleratorTable + + @see wxAcceleratorEntry, wxWindow::SetAcceleratorTable */ class wxAcceleratorTable : public wxObject { public: - //@{ /** - Loads the accelerator table from a Windows resource (Windows only). - - @param n - Number of accelerator entries. - - @param entries - The array of entries. - - @param resource - Name of a Windows accelerator. + Default ctor. */ wxAcceleratorTable(); - wxAcceleratorTable(const wxAcceleratorTable& bitmap); - wxAcceleratorTable(int n, wxAcceleratorEntry entries[]); - wxAcceleratorTable(const wxString& resource); - //@} /** - Destroys the wxAcceleratorTable object. - See @ref overview_refcountdestruct "reference-counted object destruction" for - more info. + Initializes the accelerator table from an array of wxAcceleratorEntry. + + @param n + Number of accelerator entries. + @param entries + The array of entries. */ - ~wxAcceleratorTable(); + wxAcceleratorTable(int n, const wxAcceleratorEntry entries[]); /** - Returns @true if the accelerator table is valid. + Loads the accelerator table from a Windows resource (Windows only). + + @onlyfor{wxmsw} + + @param resource + Name of a Windows accelerator. */ -#define bool IsOk() /* implementation is private */ + wxAcceleratorTable(const wxString& resource); /** - Assignment operator, using @ref overview_trefcount "reference counting". - - @param accel - Accelerator table to assign. + Destroys the wxAcceleratorTable object. + See @ref overview_refcount_destruct for more info. */ - wxAcceleratorTable operator =(const wxAcceleratorTable& accel); + virtual ~wxAcceleratorTable(); + + /** + Returns @true if the accelerator table is valid. + */ + bool IsOk() const; }; + + +// ============================================================================ +// Global functions/macros +// ============================================================================ + +/** + An empty accelerator table. +*/ +wxAcceleratorTable wxNullAcceleratorTable;