revised the first two interface headers

[wxWidgets.git] / interface / accel.h

diff --git a/interface/accel.h b/interface/accel.h
index b12465366a4c889ce6009cdd02bb0dee2d38ed53..279fe36d6548f5309fa980342f4e30acb07cf2fd 100644 (file)
--- a/interface/accel.h
+++ b/interface/accel.h
@@ -1,17 +1,38 @@
 /////////////////////////////////////////////////////////////////////////////
 // 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}
@@ -22,22 +43,23 @@
 class wxAcceleratorEntry
 {
 public:
-    //@{
+    /**
+        Default ctor.
+    */
+    wxAcceleratorEntry();
+
     /**
         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.
     */
-    wxAcceleratorEntry();
     wxAcceleratorEntry(int flags, int keyCode, int cmd);
-    //@}
 
     /**
         Returns the command identifier for the accelerator table entry.
@@ -58,13 +80,13 @@ public:
         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.
+
     */
     void Set(int flags, int keyCode, int cmd);
 };
@@ -75,20 +97,35 @@ 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 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 #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' (but not in GTK+ at present).
 
     @library{wxcore}
     @category{misc}
 
     @stdobjects
-    Objects:
     wxNullAcceleratorTable
 
     @seealso
@@ -97,27 +134,38 @@ public:
 class wxAcceleratorTable : public wxObject
 {
 public:
-    //@{
     /**
-        Loads the accelerator table from a Windows resource (Windows only).
+        Default ctor.
+    */
+    wxAcceleratorTable();
+
+    /**
+        Copy ctor.
+    */
+    wxAcceleratorTable(const wxAcceleratorTable& bitmap);
+
+    /**
+        Initializes the accelerator table from an array of wxAcceleratorEntry.
         
         @param n
             Number of accelerator entries.
         @param entries
             The array of entries.
+    */
+    wxAcceleratorTable(int n, wxAcceleratorEntry entries[]);
+
+    /**
+        Loads the accelerator table from a Windows resource (Windows only).
+        
         @param resource
             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();
 
@@ -127,10 +175,15 @@ public:
     bool IsOk() const;
 
     /**
-        Assignment operator, using @ref overview_trefcount "reference counting".
+        Assignment operator, using @ref overview_refcount "reference counting".
         
         @param accel
             Accelerator table to assign.
     */
     wxAcceleratorTable operator =(const wxAcceleratorTable& accel);
 };
+
+/**
+    An empty accelerator table.
+*/
+wxAcceleratorTable wxNullAcceleratorTable;