X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/7c913512a4c9f36e11e07ea707002fab1608d324..ce323d38d3623d0f96a633d5e22e221fc384f566:/interface/accel.h?ds=sidebyside diff --git a/interface/accel.h b/interface/accel.h index 167253fc46..761ac864a6 100644 --- a/interface/accel.h +++ b/interface/accel.h @@ -1,74 +1,130 @@ ///////////////////////////////////////////////////////////////////////////// // 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} + @category{misc} - @seealso - wxAcceleratorTable, wxWindow::SetAcceleratorTable + @see wxAcceleratorTable, wxWindow::SetAcceleratorTable */ class wxAcceleratorEntry { public: - //@{ /** Constructor. - + @param flags - One of wxACCEL_ALT, wxACCEL_SHIFT, wxACCEL_CTRL and wxACCEL_NORMAL. Indicates - which modifier key is held down. - + A combination of the wxAcceleratorEntryFlags values, which + indicates which modifier keys are held down. @param keyCode - The keycode to be detected. See Keycodes for a full list of keycodes. - + The keycode to be detected. See @ref page_keycodes for a full list of keycodes. @param cmd - The menu or control command identifier. + 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. - + A combination of the wxAcceleratorEntryFlags values, which + indicates which modifier keys are held down. @param keyCode - The keycode to be detected. See Keycodes for a full list of keycodes. - + The keycode to be detected. See @ref page_keycodes for a full list of keycodes. @param cmd - The menu or control command identifier. + 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. */ -#define void Set(int flags, int keyCode, int cmd) /* implementation is private */ + 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) + */ + bool FromString(const wxString& str); + + + wxAcceleratorEntry& operator=(const wxAcceleratorEntry& entry); + bool operator==(const wxAcceleratorEntry& entry) const; + bool operator!=(const wxAcceleratorEntry& entry) const; }; @@ -77,64 +133,82 @@ public: @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. + 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 - The object @b wxNullAcceleratorTable is defined to be a table with no data, and - is the - initial accelerator table for a window. + @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 + ::wxNullAcceleratorTable - @seealso - wxAcceleratorEntry, wxWindow::SetAcceleratorTable + @see wxAcceleratorEntry, wxWindow::SetAcceleratorTable */ class wxAcceleratorTable : public wxObject { public: - //@{ /** - Loads the accelerator table from a Windows resource (Windows only). - + Default ctor. + */ + wxAcceleratorTable(); + + /** + Initializes the accelerator table from an array of wxAcceleratorEntry. + @param n - Number of accelerator entries. - + Number of accelerator entries. @param entries - The array of entries. - + The array of entries. + */ + wxAcceleratorTable(int n, const wxAcceleratorEntry entries[]); + + /** + Loads the accelerator table from a Windows resource (Windows only). + @param resource - Name of a Windows accelerator. + Name of a Windows accelerator. */ - 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. + See @ref overview_refcount_destruct for more info. */ ~wxAcceleratorTable(); /** Returns @true if the accelerator table is valid. */ -#define bool IsOk() /* implementation is private */ - - /** - Assignment operator, using @ref overview_trefcount "reference counting". - - @param accel - Accelerator table to assign. - */ - wxAcceleratorTable operator =(const wxAcceleratorTable& accel); + bool IsOk() const; }; + + +// ============================================================================ +// Global functions/macros +// ============================================================================ + +/** + An empty accelerator table. +*/ +wxAcceleratorTable wxNullAcceleratorTable;