More initial reviews of [u*-v*] interface headers.

[wxWidgets.git] / interface / accel.h

diff --git a/interface/accel.h b/interface/accel.h
index 279fe36d6548f5309fa980342f4e30acb07cf2fd..276373333047e57d6094639e48807a87b3268f23 100644 (file)
--- a/interface/accel.h
+++ b/interface/accel.h
@@ -35,19 +35,13 @@ enum wxAcceleratorEntryFlags
     (see wxAcceleratorTable).
 
     @library{wxcore}
-    @category{FIXME}
+    @category{misc}
 
-    @seealso
-    wxAcceleratorTable, wxWindow::SetAcceleratorTable
+    @see wxAcceleratorTable, wxWindow::SetAcceleratorTable
 */
 class wxAcceleratorEntry
 {
 public:
-    /**
-        Default ctor.
-    */
-    wxAcceleratorEntry();
-
     /**
         Constructor.
 
@@ -57,9 +51,17 @@ public:
         @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.
+            The menu or control command identifier (ID).
+        @param item
+            The menu item associated with this accelerator.
     */
-    wxAcceleratorEntry(int flags, int keyCode, int cmd);
+    wxAcceleratorEntry(int flags = 0, int keyCode = 0, int cmd = 0,
+                       wxMenuItem *item = NULL);
+
+    /**
+        Copy ctor.
+    */
+    wxAcceleratorEntry(const wxAcceleratorEntry& entry);
 
     /**
         Returns the command identifier for the accelerator table entry.
@@ -76,19 +78,53 @@ public:
     */
     int GetKeyCode() const;
 
+    /**
+        Returns the menu item associated with this accelerator entry.
+    */
+    wxMenuItem *GetMenuItem() const;
+
     /**
         Sets the accelerator entry parameters.
-        
+
         @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.
+            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)
     */
-    void Set(int flags, int keyCode, int cmd);
+    bool FromString(const wxString& str);
+
+
+    wxAcceleratorEntry& operator=(const wxAcceleratorEntry& entry);
+    bool operator==(const wxAcceleratorEntry& entry) const;
+    bool operator!=(const wxAcceleratorEntry& entry) const;
 };
 
 
@@ -97,10 +133,9 @@ 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
+    The object ::wxNullAcceleratorTable is defined to be a table with no data, and
     is the initial accelerator table for a window.
 
     Example:
@@ -120,16 +155,15 @@ public:
     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).
+    'OK'.
 
     @library{wxcore}
     @category{misc}
 
     @stdobjects
-    wxNullAcceleratorTable
+    ::wxNullAcceleratorTable
 
-    @seealso
-    wxAcceleratorEntry, wxWindow::SetAcceleratorTable
+    @see wxAcceleratorEntry, wxWindow::SetAcceleratorTable
 */
 class wxAcceleratorTable : public wxObject
 {
@@ -139,50 +173,43 @@ public:
     */
     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[]);
+    wxAcceleratorTable(int n, const wxAcceleratorEntry entries[]);
 
     /**
         Loads the accelerator table from a Windows resource (Windows only).
-        
+
+        @onlyfor{wxmsw}
+
         @param resource
             Name of a Windows accelerator.
     */
     wxAcceleratorTable(const wxString& resource);
-    //@}
 
     /**
         Destroys the wxAcceleratorTable object.
         See @ref overview_refcount_destruct for more info.
     */
-    ~wxAcceleratorTable();
+    virtual ~wxAcceleratorTable();
 
     /**
         Returns @true if the accelerator table is valid.
     */
     bool IsOk() const;
-
-    /**
-        Assignment operator, using @ref overview_refcount "reference counting".
-        
-        @param accel
-            Accelerator table to assign.
-    */
-    wxAcceleratorTable operator =(const wxAcceleratorTable& accel);
 };
 
+
+// ============================================================================
+// Global functions/macros
+// ============================================================================
+
 /**
     An empty accelerator table.
 */