]> git.saurik.com Git - wxWidgets.git/blobdiff - interface/wx/menu.h
support for iPhone callbacks
[wxWidgets.git] / interface / wx / menu.h
index f0d5009d503ac28e58ba76002ddb07c80ac152b7..a6b5cbe0d907c999ea46a0f641eca7e472e54558 100644 (file)
@@ -3,7 +3,7 @@
 // Purpose:     interface of wxMenuBar
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
-// Licence:     wxWindows license
+// Licence:     wxWindows licence
 /////////////////////////////////////////////////////////////////////////////
 
 /**
@@ -53,6 +53,10 @@ public:
             the menu bar.
         @param style
             If wxMB_DOCKABLE the menu bar can be detached (wxGTK only).
+
+        @beginWxPerlOnly
+        Not supported by wxPerl.
+        @endWxPerlOnly
     */
     wxMenuBar(size_t n, wxMenu* menus[], const wxString titles[],
               long style = 0);
@@ -69,7 +73,7 @@ public:
         @param menu
             The menu to add. Do not deallocate this menu after calling Append().
         @param title
-            The title of the menu.
+            The title of the menu, must be non-empty.
 
         @return @true on success, @false if an error occurred.
 
@@ -103,6 +107,16 @@ public:
     */
     void Enable(int id, bool enable);
 
+    /**
+        Returns true if the menu with the given index is enabled.
+
+        @param pos
+            The menu position (0-based)
+
+        @since 2.9.4
+    */
+    bool IsEnabledTop(size_t pos) const;
+
     /**
         Enables or disables a whole menu.
 
@@ -124,8 +138,14 @@ public:
             If not @NULL, menu will get set to the associated menu.
 
         @return The found menu item object, or @NULL if one was not found.
+
+        @beginWxPerlOnly
+        In wxPerl this method takes just the @a id parameter;
+        in scalar context it returns the associated @c Wx::MenuItem, in list
+        context it returns a 2-element list (item, submenu).
+        @endWxPerlOnly
     */
-    virtual wxMenuItem* FindItem(int id, wxMenu* menu = NULL) const;
+    virtual wxMenuItem* FindItem(int id, wxMenu** menu = NULL) const;
 
     /**
         Returns the index of the menu with the given @a title or @c wxNOT_FOUND if no
@@ -363,6 +383,37 @@ public:
         @remarks Use only after the menubar has been associated with a frame.
     */
     virtual void SetMenuLabel(size_t pos, const wxString& label);
+    
+    /**        
+        Enables you to set the global menubar on Mac, that is, the menubar displayed
+        when the app is running without any frames open.
+        
+        @param menubar
+            The menubar to set.
+            
+        @remarks Only exists on Mac, other platforms do not have this method. 
+
+        @onlyfor{wxosx}
+    */
+    static void MacSetCommonMenuBar(wxMenuBar* menubar);
+    
+    /**        
+        Enables you to get the global menubar on Mac, that is, the menubar displayed
+        when the app is running without any frames open.
+        
+        @return The global menubar.
+            
+        @remarks Only exists on Mac, other platforms do not have this method. 
+
+        @onlyfor{wxosx}
+    */
+    static wxMenuBar* MacGetCommonMenuBar();
+
+    wxFrame *GetFrame() const;
+    bool IsAttached() const;
+    virtual void Attach(wxFrame *frame);
+    virtual void Detach();
+
 };
 
 
@@ -376,15 +427,15 @@ public:
 
     A menu item has an integer ID associated with it which can be used to
     identify the selection, or to change the menu item in some way. A menu item
-    with a special identifier -1 is a separator item and doesn't have an
-    associated command but just makes a separator line appear in the menu.
+    with a special identifier @e wxID_SEPARATOR is a separator item and doesn't
+    have an associated command but just makes a separator line appear in the
+    menu.
 
     @note
     Please note that @e wxID_ABOUT and @e wxID_EXIT are predefined by wxWidgets
     and have a special meaning since entries using these IDs will be taken out
     of the normal menus under MacOS X and will be inserted into the system menu
     (following the appropriate MacOS X interface guideline).
-    On PalmOS @e wxID_EXIT is disabled according to Palm OS Companion guidelines.
 
     Menu items may be either @e normal items, @e check items or @e radio items.
     Normal items don't have any special properties while the check items have a
@@ -406,9 +457,13 @@ public:
 
     @section menu_allocation Allocation strategy
 
-    All menus except the popup ones must be created on the @b heap.
-    All menus attached to a menubar or to another menu will be deleted by their
-    parent when it is deleted.
+    All menus must be created on the @b heap because all menus attached to a
+    menubar or to another menu will be deleted by their parent when it is
+    deleted. The only exception to this rule are the popup menus (i.e. menus
+    used with wxWindow::PopupMenu()) as wxWidgets does not destroy them to
+    allow reusing the same menu more than once. But the exception applies only
+    to the menus themselves and not to any submenus of popup menus which are
+    still destroyed by wxWidgets as usual and so must be heap-allocated.
 
     As the frame menubar is deleted by the frame itself, it means that normally
     all menus used are deleted automatically.
@@ -419,7 +474,7 @@ public:
     If the menu is part of a menubar, then wxMenuBar event processing is used.
 
     With a popup menu (see wxWindow::PopupMenu), there is a variety of ways to
-    handle a menu selection event (@c wxEVT_COMMAND_MENU_SELECTED):
+    handle a menu selection event (@c wxEVT_MENU):
     - Provide @c EVT_MENU handlers in the window which pops up the menu, or in an
       ancestor of that window (the simplest method);
     - Derive a new class from wxMenu and define event table entries using the @c EVT_MENU macro;
@@ -427,7 +482,7 @@ public:
       specifying an object whose class has @c EVT_MENU entries;
 
     Note that instead of static @c EVT_MENU macros you can also use dynamic
-    connection; see @ref overview_events_connect.
+    connection; see @ref overview_events_bind.
 
     @library{wxcore}
     @category{menus}
@@ -438,6 +493,12 @@ public:
 class wxMenu : public wxEvtHandler
 {
 public:
+
+    /**
+        Constructs a wxMenu object.
+    */
+    wxMenu();
+    
     /**
         Constructs a wxMenu object.
 
@@ -476,45 +537,27 @@ public:
             The menu command identifier.
         @param item
             The string to appear on the menu item.
+            See wxMenuItem::SetItemLabel() for more details.
         @param helpString
             An optional help string associated with the item.
-            By default, the handler for the wxEVT_MENU_HIGHLIGHT event displays
+            By default, the handler for the @c wxEVT_MENU_HIGHLIGHT event displays
             this string in the status line.
         @param kind
-            May be wxITEM_SEPARATOR, wxITEM_NORMAL, wxITEM_CHECK or wxITEM_RADIO
+            May be @c wxITEM_SEPARATOR, @c wxITEM_NORMAL, @c wxITEM_CHECK or @c wxITEM_RADIO.
+
+        Example:
+        @code
+        m_pFileMenu->Append(ID_NEW_FILE, "&New file\tCTRL+N", "Creates a new XYZ document");
+        @endcode
+        or even better for stock menu items (see wxMenuItem::wxMenuItem):
+        @code
+        m_pFileMenu->Append(wxID_NEW, "", "Creates a new XYZ document");
+        @endcode
 
         @remarks
         This command can be used after the menu has been shown, as well as on
         initial creation of a menu or menubar.
 
-        The item string for the normal menu items (not submenus or separators)
-        may include the accelerator which can be used to activate the menu item
-        from keyboard.
-        The accelerator string follows the item label and is separated from it
-        by a TAB character ('\\t').
-
-        Its general syntax is any combination of "CTRL", "ALT" and "SHIFT" strings
-        (case doesn't matter) separated by either '-' or '+' characters and followed
-        by the accelerator itself.
-        The accelerator may be any alphanumeric character, any function key
-        (from F1 to F12) or one of the special characters listed in the table
-        below (again, case doesn't matter):
-
-        - DEL or DELETE: Delete key
-        - INS or INSERT: Insert key
-        - ENTER or RETURN: Enter key
-        - PGUP: PageUp key
-        - PGDN: PageDown key
-        - LEFT: Left cursor arrow key
-        - RIGHT: Right cursor arrow key
-        - UP: Up cursor arrow key
-        - DOWN: Down cursor arrow key
-        - HOME: Home key
-        - END: End key
-        - SPACE: Space
-        - TAB: Tab key
-        - ESC: or ESCAPE Escape key (Windows only)
-
         @see AppendSeparator(), AppendCheckItem(), AppendRadioItem(),
              AppendSubMenu(), Insert(), SetLabel(), GetHelpString(),
              SetHelpString(), wxMenuItem
@@ -536,7 +579,7 @@ public:
             Pull-right submenu.
         @param helpString
             An optional help string associated with the item.
-            By default, the handler for the wxEVT_MENU_HIGHLIGHT event displays
+            By default, the handler for the @c wxEVT_MENU_HIGHLIGHT event displays
             this string in the status line.
 
         @see AppendSeparator(), AppendCheckItem(), AppendRadioItem(),
@@ -650,7 +693,7 @@ public:
         @param id
             Id of the menu item to be deleted.
 
-        @see FindItem(), Deletes(), Remove()
+        @see FindItem(), Delete(), Remove()
     */
     bool Destroy(int id);
 
@@ -662,7 +705,7 @@ public:
         @param item
             Menu item to be deleted.
 
-        @see FindItem(), Deletes(), Remove()
+        @see FindItem(), Delete(), Remove()
     */
     bool Destroy(wxMenuItem* item);
 
@@ -777,16 +820,13 @@ public:
         wxMenuItemList is a pseudo-template list class containing wxMenuItem
         pointers, see wxList.
     */
-    wxMenuItemList& GetMenuItems() const;
+    wxMenuItemList& GetMenuItems();
     const wxMenuItemList& GetMenuItems() const;
     //@}
 
     /**
         Returns the title of the menu.
 
-        @remarks This is relevant only to popup menus, use
-                 wxMenuBar::GetMenuLabel for the menus in the menubar.
-
         @see SetTitle()
     */
     const wxString& GetTitle() const;
@@ -799,7 +839,7 @@ public:
 
         @see Append(), Prepend()
     */
-    wxMenuItem* Insert(size_t pos, wxMenuItem* item);
+    wxMenuItem* Insert(size_t pos, wxMenuItem* menuItem);
 
     /**
         Inserts the given @a item before the position @a pos.
@@ -862,7 +902,7 @@ public:
     bool IsEnabled(int id) const;
 
     /**
-        Inserts the given @a item at position 0, i.e. before all the other
+        Inserts the given @a item at position 0, i.e.\ before all the other
         existing items.
 
         @see Append(), Insert()
@@ -870,7 +910,7 @@ public:
     wxMenuItem* Prepend(wxMenuItem* item);
 
     /**
-        Inserts the given @a item at position 0, i.e. before all the other
+        Inserts the given @a item at position 0, i.e.\ before all the other
         existing items.
 
         @see Append(), Insert()
@@ -956,8 +996,9 @@ public:
         @param title
             The title to set.
 
-        @remarks This is relevant only to popup menus, use
-                 wxMenuBar::SetLabelTop for the menus in the menubar.
+        @remarks Notice that you can only call this method directly for the
+            popup menus, to change the title of a menu that is part of a menu
+            bar you need to use wxMenuBar::SetLabelTop().
 
         @see GetTitle()
     */
@@ -971,5 +1012,18 @@ public:
         but the application may call it at other times if required.
     */
     void UpdateUI(wxEvtHandler* source = NULL);
+
+    
+    void SetInvokingWindow(wxWindow *win);
+    wxWindow *GetInvokingWindow() const;
+    wxWindow *GetWindow() const;
+    long GetStyle() const;
+    void SetParent(wxMenu *parent);
+    wxMenu *GetParent() const;
+
+    virtual void Attach(wxMenuBar *menubar);
+    virtual void Detach();
+    bool IsAttached() const;
+
 };