more utils.h fixes

[wxWidgets.git] / interface / accel.h

diff --git a/interface/accel.h b/interface/accel.h
index 167253fc46259b2ec71b3460fa0050f7288da053..761ac864a6a9ad7b453376d5c2bac7ff8dad9a66 100644 (file)
--- a/interface/accel.h
+++ b/interface/accel.h
@@ -1,74 +1,130 @@
 /////////////////////////////////////////////////////////////////////////////
 // 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}
+    @category{misc}

 
 

-    @seealso
-    wxAcceleratorTable, wxWindow::SetAcceleratorTable
+    @see wxAcceleratorTable, wxWindow::SetAcceleratorTable

 */
 class wxAcceleratorEntry
 {
 public:
 */
 class wxAcceleratorEntry
 {
 public:

-    //@{

     /**
         Constructor.
     /**
         Constructor.

-        
+

         @param flags
         @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
         @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
         @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.
     */
 
     /**
         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
         @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
         @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
         @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
     @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
 
     @library{wxcore}
     @category{misc}
 
     @stdobjects

-    Objects:
-    wxNullAcceleratorTable
+    ::wxNullAcceleratorTable

 
 

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

 */
 class wxAcceleratorTable : public wxObject
 {
 public:
 */
 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
         @param n

-        Number of accelerator entries.
-        
+            Number of accelerator entries.

         @param 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
         @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);
     wxAcceleratorTable(const wxString& resource);

-    //@}

 
     /**
         Destroys the wxAcceleratorTable object.
 
     /**
         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.
     */
     */
     ~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;