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

[wxWidgets.git] / interface / accel.h

diff --git a/interface/accel.h b/interface/accel.h
index 5ae1b3f4e2cdf9ee958831c5d2e3fcc5738ec329..276373333047e57d6094639e48807a87b3268f23 100644 (file)
--- a/interface/accel.h
+++ b/interface/accel.h
@@ -1,140 +1,216 @@
 /////////////////////////////////////////////////////////////////////////////
 // Name:        accel.h
 /////////////////////////////////////////////////////////////////////////////
 // Name:        accel.h

-// Purpose:     documentation for wxAcceleratorEntry class
+// Purpose:     interface of wxAccelerator* classes

 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Licence:     wxWindows license
 /////////////////////////////////////////////////////////////////////////////
 
 // 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}
 /**
     @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}
     @library{wxcore}

-    @category{FIXME}
-    
-    @seealso
-    wxAcceleratorTable, wxWindow::SetAcceleratorTable
+    @category{misc}
+
+    @see wxAcceleratorTable, wxWindow::SetAcceleratorTable

 */
 */

-class wxAcceleratorEntry 
+class wxAcceleratorEntry

 {
 public:
 {
 public:

-    //@{

     /**
         Constructor.
     /**
         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.
     */
 
     /**
         Returns the command identifier for the accelerator table entry.
     */

-    int GetCommand();
+    int GetCommand() const;

 
     /**
         Returns the flags for the accelerator table entry.
     */
 
     /**
         Returns the flags for the accelerator table entry.
     */

-    int GetFlags();
+    int GetFlags() const;

 
     /**
         Returns the keycode for the accelerator table entry.
     */
 
     /**
         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.
 
     /**
         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}
 };
 
 
 /**
     @class wxAcceleratorTable
     @wxheader{accel.h}

-    
+

     An accelerator table allows the application to specify a table of keyboard
     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}
     @library{wxcore}
     @category{misc}

-    
+

     @stdobjects
     @stdobjects

-    Objects:
-    wxNullAcceleratorTable
-    
-    @seealso
-    wxAcceleratorEntry, wxWindow::SetAcceleratorTable
+    ::wxNullAcceleratorTable
+
+    @see wxAcceleratorEntry, wxWindow::SetAcceleratorTable

 */
 class wxAcceleratorTable : public wxObject
 {
 public:
 */
 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();

-        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;