Corrected library association

[wxWidgets.git] / interface / wx / mdi.h

diff --git a/interface/wx/mdi.h b/interface/wx/mdi.h
index 3d5f3b80bc95cc280f115f71f2b03dcab8b576a1..ff39121e6def2f3bbe37b93d5f0b9ef023152d51 100644 (file)
--- a/interface/wx/mdi.h
+++ b/interface/wx/mdi.h
@@ -8,20 +8,40 @@
 
 /**
     @class wxMDIClientWindow
 
 /**
     @class wxMDIClientWindow

-    @wxheader{mdi.h}

 
     An MDI client window is a child of wxMDIParentFrame, and manages zero or
     more wxMDIChildFrame objects.
 
 
     An MDI client window is a child of wxMDIParentFrame, and manages zero or
     more wxMDIChildFrame objects.
 

+    @remarks
+
+    The client window is the area where MDI child windows exist. It doesn't have to
+    cover the whole parent frame; other windows such as toolbars and a help window
+    might coexist with it. There can be scrollbars on a client window, which are
+    controlled by the parent window style.
+
+    The wxMDIClientWindow class is usually adequate without further derivation, and
+    it is created automatically when the MDI parent frame is created. If the application
+    needs to derive a new class, the function wxMDIParentFrame::OnCreateClient() must
+    be overridden in order to give an opportunity to use a different class of client
+    window.
+
+    Under Windows 95, the client window will automatically have a sunken border style
+    when the active child is not maximized, and no border style when a child is maximized.
+

     @library{wxcore}
     @library{wxcore}

-    @category{FIXME}
+    @category{managedwnd}

 
     @see wxMDIChildFrame, wxMDIParentFrame, wxFrame
 */
 class wxMDIClientWindow : public wxWindow
 {
 public:
 
     @see wxMDIChildFrame, wxMDIParentFrame, wxFrame
 */
 class wxMDIClientWindow : public wxWindow
 {
 public:

-    //@{
+
+    /**
+        Default constructor.
+    */
+    wxMDIClientWindow();
+

     /**
         Constructor, creating the window.
 
     /**
         Constructor, creating the window.
 


@@ -30,44 +50,60 @@ public:
         @param style
             The window style. Currently unused.
 
         @param style
             The window style. Currently unused.
 

-        @remarks The second style of constructor is called within
-                 wxMDIParentFrame::OnCreateClient.
+        @remarks This constructor is called within wxMDIParentFrame::OnCreateClient().

 
 

-        @see wxMDIParentFrame::wxMDIParentFrame, wxMDIParentFrame::OnCreateClient
+        @see wxMDIParentFrame::wxMDIParentFrame(), wxMDIParentFrame::OnCreateClient()

     */
     */

-    wxMDIClientWindow();

     wxMDIClientWindow(wxMDIParentFrame* parent, long style = 0);
     wxMDIClientWindow(wxMDIParentFrame* parent, long style = 0);

-    //@}

 
     /**
         Destructor.
     */
 
     /**
         Destructor.
     */

-    ~wxMDIClientWindow();
+    virtual ~wxMDIClientWindow();

 
     /**
         Used in two-step frame construction. See wxMDIClientWindow()
         for further details.
     */
 
     /**
         Used in two-step frame construction. See wxMDIClientWindow()
         for further details.
     */

-    bool CreateClient(wxMDIParentFrame* parent, long style = 0);
+    virtual bool CreateClient(wxMDIParentFrame* parent, long style = 0);

 };
 
 
 
 /**
     @class wxMDIParentFrame
 };
 
 
 
 /**
     @class wxMDIParentFrame

-    @wxheader{mdi.h}

 
     An MDI (Multiple Document Interface) parent frame is a window which can contain
     MDI child frames in its own 'desktop'. It is a convenient way to avoid window
 
     An MDI (Multiple Document Interface) parent frame is a window which can contain
     MDI child frames in its own 'desktop'. It is a convenient way to avoid window

-    clutter,
-    and is used in many popular Windows applications, such as Microsoft Word(TM).
+    clutter, and is used in many popular Windows applications, such as Microsoft Word(TM).
+
+    @remarks
+
+    There may be multiple MDI parent frames in a single application, but this probably
+    only makes sense within programming development environments.
+
+    Child frames may be of class wxMDIChildFrame (contained within the parent frame)
+    or wxFrame (shown as a top-level frame).
+
+    An MDI parent frame always has a wxMDIClientWindow associated with it, which is the
+    parent for MDI child frames. This client window may be resized to accommodate non-MDI
+    windows, as seen in Microsoft Visual C++ (TM) and Microsoft Publisher (TM), where
+    a documentation window is placed to one side of the workspace.
+
+    MDI remains popular despite dire warnings from Microsoft itself that MDI is an obsolete
+    user interface style.
+
+    The implementation is native in Windows, and simulated under Motif. Under Motif, the
+    child window frames will often have a different appearance from other frames because
+    the window decorations are simulated.
+

 
     @beginStyleTable
     @style{wxCAPTION}
            Puts a caption on the frame.
     @style{wxDEFAULT_FRAME_STYLE}
 
     @beginStyleTable
     @style{wxCAPTION}
            Puts a caption on the frame.
     @style{wxDEFAULT_FRAME_STYLE}

-           Defined as wxMINIMIZE_BOX |  wxMAXIMIZE_BOX |  wxTHICK_FRAME |
-           wxSYSTEM_MENU |  wxCAPTION.
+           Defined as @c wxMINIMIZE_BOX | @c wxMAXIMIZE_BOX | @c wxTHICK_FRAME |
+           @c wxSYSTEM_MENU | @c wxCAPTION.

     @style{wxHSCROLL}
            Displays a horizontal scrollbar in the client window, allowing the
            user to view child frames that are off the current view.
     @style{wxHSCROLL}
            Displays a horizontal scrollbar in the client window, allowing the
            user to view child frames that are off the current view.


@@ -78,12 +114,12 @@ public:
     @style{wxMAXIMIZE_BOX}
            Displays a maximize box on the frame (Windows and Motif only).
     @style{wxMINIMIZE}
     @style{wxMAXIMIZE_BOX}
            Displays a maximize box on the frame (Windows and Motif only).
     @style{wxMINIMIZE}

-           Identical to wxICONIZE.
+           Identical to @c wxICONIZE.

     @style{wxMINIMIZE_BOX}
            Displays a minimize box on the frame (Windows and Motif only).
     @style{wxRESIZE_BORDER}
            Displays a resizeable border around the window (Motif only; for
     @style{wxMINIMIZE_BOX}
            Displays a minimize box on the frame (Windows and Motif only).
     @style{wxRESIZE_BORDER}
            Displays a resizeable border around the window (Motif only; for

-           Windows, it is implicit in wxTHICK_FRAME).
+           Windows, it is implicit in @c wxTHICK_FRAME).

     @style{wxSTAY_ON_TOP}
            Stay on top of other windows (Windows only).
     @style{wxSYSTEM_MENU}
     @style{wxSTAY_ON_TOP}
            Stay on top of other windows (Windows only).
     @style{wxSYSTEM_MENU}


@@ -106,7 +142,12 @@ public:
 class wxMDIParentFrame : public wxFrame
 {
 public:
 class wxMDIParentFrame : public wxFrame
 {
 public:

-    //@{
+
+    /**
+        Default constructor.
+    */
+    wxMDIParentFrame();
+

     /**
         Constructor, creating the window.
 
     /**
         Constructor, creating the window.
 


@@ -114,76 +155,74 @@ public:
             The window parent. This should be @NULL.
         @param id
             The window identifier. It may take a value of -1 to indicate a default
             The window parent. This should be @NULL.
         @param id
             The window identifier. It may take a value of -1 to indicate a default

-        value.
+            value.

         @param title
             The caption to be displayed on the frame's title bar.
         @param pos
         @param title
             The caption to be displayed on the frame's title bar.
         @param pos

-            The window position. The value wxDefaultPosition indicates a default position,
-        chosen by
-            either the windowing system or wxWidgets, depending on platform.
+            The window position. The value @c wxDefaultPosition indicates a default position,
+            chosen by either the windowing system or wxWidgets, depending on platform.

         @param size
         @param size

-            The window size. The value wxDefaultSize indicates a default size, chosen by
+            The window size. The value @c wxDefaultSize indicates a default size, chosen by

             either the windowing system or wxWidgets, depending on platform.
         @param style
             The window style. See wxMDIParentFrame.
         @param name
             either the windowing system or wxWidgets, depending on platform.
         @param style
             The window style. See wxMDIParentFrame.
         @param name

-            The name of the window. This parameter is used to associate a name with the
-        item,
-            allowing the application user to set Motif resource values for
-            individual windows.
+            The name of the window. This parameter is used to associate a name
+            with the item, allowing the application user to set Motif resource values
+            for individual windows.

 
         @remarks During the construction of the frame, the client window will be
 
         @remarks During the construction of the frame, the client window will be

-                 created. To use a different class from
-                 wxMDIClientWindow, override
+                 created. To use a different class from wxMDIClientWindow, override

                  OnCreateClient().
                  OnCreateClient().

+                 Under Windows 95, the client window will automatically have a
+                 sunken border style when the active child is not maximized,
+                 and no border style when a child is maximized.

 
         @see Create(), OnCreateClient()
     */
 
         @see Create(), OnCreateClient()
     */

-    wxMDIParentFrame();

     wxMDIParentFrame(wxWindow* parent, wxWindowID id,
                      const wxString& title,
                      const wxPoint& pos = wxDefaultPosition,
                      const wxSize& size = wxDefaultSize,
                      long style = wxDEFAULT_FRAME_STYLE | wxVSCROLL | wxHSCROLL,
                      const wxString& name = "frame");
     wxMDIParentFrame(wxWindow* parent, wxWindowID id,
                      const wxString& title,
                      const wxPoint& pos = wxDefaultPosition,
                      const wxSize& size = wxDefaultSize,
                      long style = wxDEFAULT_FRAME_STYLE | wxVSCROLL | wxHSCROLL,
                      const wxString& name = "frame");

-    //@}

 
     /**
         Destructor. Destroys all child windows and menu bar if present.
     */
 
     /**
         Destructor. Destroys all child windows and menu bar if present.
     */

-    ~wxMDIParentFrame();
+    virtual ~wxMDIParentFrame();

 
     /**
         Activates the MDI child following the currently active one.
 
         @see ActivatePrevious()
     */
 
     /**
         Activates the MDI child following the currently active one.
 
         @see ActivatePrevious()
     */

-    void ActivateNext();
+    virtual void ActivateNext();

 
     /**
         Activates the MDI child preceding the currently active one.
 
         @see ActivateNext()
     */
 
     /**
         Activates the MDI child preceding the currently active one.
 
         @see ActivateNext()
     */

-    void ActivatePrevious();
+    virtual void ActivatePrevious();

 
     /**
         Arranges any iconized (minimized) MDI child windows.
 
         @see Cascade(), Tile()
     */
 
     /**
         Arranges any iconized (minimized) MDI child windows.
 
         @see Cascade(), Tile()
     */

-    void ArrangeIcons();
+    virtual void ArrangeIcons();

 
     /**
         Arranges the MDI child windows in a cascade.
 
         @see Tile(), ArrangeIcons()
     */
 
     /**
         Arranges the MDI child windows in a cascade.
 
         @see Tile(), ArrangeIcons()
     */

-    void Cascade();
+    virtual void Cascade();

 
     /**
 
     /**

-        Used in two-step frame construction. See wxMDIParentFrame()
-        for further details.
+        Used in two-step frame construction.
+        See wxMDIParentFrame() for further details.

     */
     bool Create(wxWindow* parent, wxWindowID id,
                 const wxString& title,
     */
     bool Create(wxWindow* parent, wxWindowID id,
                 const wxString& title,


@@ -205,14 +244,39 @@ public:
         @param height
             Receives the client height in pixels.
 
         @param height
             Receives the client height in pixels.
 

-        @remarks The client area is the area which may be drawn on by the
-                 programmer, excluding title bar, border, status bar,
-                 and toolbar if present.
+        @remarks

 
 

-        @see GetToolBar(), SetToolBar(),
-             wxMDIClientWindow
+        The client area is the area which may be drawn on by the programmer, excluding
+        title bar, border, status bar, and toolbar if present.
+
+        If you wish to manage your own toolbar (or perhaps you have more than one),
+        provide an @b OnSize event handler. Call GetClientSize() to find how much space
+        there is for your windows and don't forget to set the size and position of
+        the MDI client window as well as your toolbar and other windows (but not the
+        status bar).
+
+        If you have set a toolbar with wxMDIParentFrame::SetToolbar(), the client size
+        returned will have subtracted the toolbar height. However, the available positions
+        for the client window and other windows of the frame do not start at zero - you
+        must add the toolbar height.
+
+        The position and size of the status bar and toolbar (if known to the frame) are
+        always managed by wxMDIParentFrame, regardless of what behaviour is defined in
+        your @b OnSize event handler. However, the client window position and size are always
+        set in @b OnSize, so if you override this event handler, make sure you deal with the
+        client window.
+
+        You do not have to manage the size and position of MDI child windows, since they
+        are managed automatically by the client window.
+
+        @see GetToolBar(), SetToolBar(), wxMDIClientWindow
+
+        @beginWxPythonOnly
+        The wxPython version of this method takes no arguments and returns a tuple containing
+        width and height.
+        @endWxPythonOnly

     */
     */

-    virtual void GetClientSize(int* width, int* height) const;
+    void GetClientSize(int* width, int* height) const;

 
     /**
         Returns a pointer to the client window.
 
     /**
         Returns a pointer to the client window.


@@ -237,15 +301,23 @@ public:
 
     /**
         Override this to return a different kind of client window. If you override this
 
     /**
         Override this to return a different kind of client window. If you override this

-        function,
-        you must create your parent frame in two stages, or your function will never be
-        called,
-        due to the way C++ treats virtual functions called from constructors. For
-        example:
+        function, you must create your parent frame in two stages, or your function will
+        never be called, due to the way C++ treats virtual functions called from constructors.
+        For example:
+
+        @code
+        frame = new MyParentFrame;
+        frame->Create(parent, myParentFrameId, wxT("My Parent Frame"));
+        @endcode

 
 

-        @remarks You might wish to derive from wxMDIClientWindow in order to
-                 implement different erase behaviour, for example, such
-                 as painting a bitmap on the background.
+        @remarks
+
+        You might wish to derive from wxMDIClientWindow in order to implement different
+        erase behaviour, for example, such as painting a bitmap on the background.
+
+        Note that it is probably impossible to have a client window that scrolls
+        as well as painting a bitmap or pattern, since in @b OnScroll, the scrollbar
+        positions always return zero.

 
         @see GetClientWindow(), wxMDIClientWindow
     */
 
         @see GetClientWindow(), wxMDIClientWindow
     */


@@ -259,36 +331,51 @@ public:
         @param toolbar
             Toolbar to manage.
 
         @param toolbar
             Toolbar to manage.
 

-        @remarks When the frame is resized, the toolbar is resized to be the
-                 width of the frame client area, and the toolbar height
-                 is kept the same.
+        @remarks
+
+        When the frame is resized, the toolbar is resized to be the width of the frame
+        client area, and the toolbar height is kept the same.
+
+        When the frame is resized, the toolbar is resized to be the width of the frame
+        client area, and the toolbar height is kept the same.
+
+        The parent of the toolbar must be this frame.
+
+        If you wish to manage your own toolbar (or perhaps you have more than one),
+        don't call this function, and instead manage your subwindows and the MDI client
+        window by providing an @b OnSize event handler. Call wxMDIParentFrame::GetClientSize()
+        to find how much space there is for your windows.
+
+        Note that SDI (normal) frames and MDI child windows must always have their toolbars
+        managed by the application.

 
         @see GetToolBar(), GetClientSize()
     */
     virtual void SetToolBar(wxWindow* toolbar);
 
     /**
 
         @see GetToolBar(), GetClientSize()
     */
     virtual void SetToolBar(wxWindow* toolbar);
 
     /**

-        Call this to change the current Window menu. Ownership of the menu object
-        passes to
-        the frame when you call this function.
+        Call this to change the current Window menu.
+        Ownership of the menu object passes to the frame when you call this function.
+

         This call is available under Windows only.
         This call is available under Windows only.

-        To remove the window completely, use the wxFRAME_NO_WINDOW_MENU window style.
+
+        To remove the window completely, use the @c wxFRAME_NO_WINDOW_MENU window style.

     */
     void SetWindowMenu(wxMenu* menu);
 
     /**
         Tiles the MDI child windows either horizontally or vertically depending on
     */
     void SetWindowMenu(wxMenu* menu);
 
     /**
         Tiles the MDI child windows either horizontally or vertically depending on

-        whether @a orient is wxHORIZONTAL or wxVERTICAL.
+        whether @a orient is @c wxHORIZONTAL or @c wxVERTICAL.
+

         Currently only implemented for MSW, does nothing under the other platforms.
     */
         Currently only implemented for MSW, does nothing under the other platforms.
     */

-    void Tile(wxOrientation orient = wxHORIZONTAL);
+    virtual void Tile(wxOrientation orient = wxHORIZONTAL);

 };
 
 
 
 /**
     @class wxMDIChildFrame
 };
 
 
 
 /**
     @class wxMDIChildFrame

-    @wxheader{mdi.h}

 
     An MDI child frame is a frame that can only exist on a wxMDIClientWindow,
     which is itself a child of wxMDIParentFrame.
 
     An MDI child frame is a frame that can only exist on a wxMDIClientWindow,
     which is itself a child of wxMDIParentFrame.


@@ -297,8 +384,8 @@ public:
     @style{wxCAPTION}
            Puts a caption on the frame.
     @style{wxDEFAULT_FRAME_STYLE}
     @style{wxCAPTION}
            Puts a caption on the frame.
     @style{wxDEFAULT_FRAME_STYLE}

-           Defined as wxMINIMIZE_BOX |  wxMAXIMIZE_BOX |  wxTHICK_FRAME |
-           wxSYSTEM_MENU |  wxCAPTION.
+           Defined as @c wxMINIMIZE_BOX | @c wxMAXIMIZE_BOX | @c wxTHICK_FRAME |
+           @c wxSYSTEM_MENU | @c wxCAPTION.

     @style{wxICONIZE}
            Display the frame iconized (minimized) (Windows only).
     @style{wxMAXIMIZE}
     @style{wxICONIZE}
            Display the frame iconized (minimized) (Windows only).
     @style{wxMAXIMIZE}


@@ -306,12 +393,12 @@ public:
     @style{wxMAXIMIZE_BOX}
            Displays a maximize box on the frame (Windows and Motif only).
     @style{wxMINIMIZE}
     @style{wxMAXIMIZE_BOX}
            Displays a maximize box on the frame (Windows and Motif only).
     @style{wxMINIMIZE}

-           Identical to wxICONIZE.
+           Identical to @c wxICONIZE.

     @style{wxMINIMIZE_BOX}
            Displays a minimize box on the frame (Windows and Motif only).
     @style{wxRESIZE_BORDER}
            Displays a resizeable border around the window (Motif only; for
     @style{wxMINIMIZE_BOX}
            Displays a minimize box on the frame (Windows and Motif only).
     @style{wxRESIZE_BORDER}
            Displays a resizeable border around the window (Motif only; for

-           Windows, it is implicit in wxTHICK_FRAME).
+           Windows, it is implicit in @c wxTHICK_FRAME).

     @style{wxSTAY_ON_TOP}
            Stay on top of other windows (Windows only).
     @style{wxSYSTEM_MENU}
     @style{wxSTAY_ON_TOP}
            Stay on top of other windows (Windows only).
     @style{wxSYSTEM_MENU}


@@ -320,6 +407,19 @@ public:
            Displays a thick frame around the window (Windows and Motif only).
     @endStyleTable
 
            Displays a thick frame around the window (Windows and Motif only).
     @endStyleTable
 

+    @remarks
+    Although internally an MDI child frame is a child of the MDI client window,
+    in wxWidgets you create it as a child of wxMDIParentFrame.
+    You can usually forget that the client window exists.
+    MDI child frames are clipped to the area of the MDI client window, and may
+    be iconized on the client window.
+    You can associate a menubar with a child frame as usual, although an MDI
+    child doesn't display its menubar under its own title bar.
+    The MDI parent frame's menubar will be changed to reflect the currently
+    active child frame.
+    If there are currently no children, the parent frame's own menubar will
+    be displayed.
+

     @library{wxcore}
     @category{managedwnd}
 
     @library{wxcore}
     @category{managedwnd}
 


@@ -328,7 +428,12 @@ public:
 class wxMDIChildFrame : public wxFrame
 {
 public:
 class wxMDIChildFrame : public wxFrame
 {
 public:

-    //@{
+
+    /**
+        Default constructor.
+    */
+    wxMDIChildFrame();
+

     /**
         Constructor, creating the window.
 
     /**
         Constructor, creating the window.
 


@@ -336,52 +441,46 @@ public:
             The window parent. This should not be @NULL.
         @param id
             The window identifier. It may take a value of -1 to indicate a default
             The window parent. This should not be @NULL.
         @param id
             The window identifier. It may take a value of -1 to indicate a default

-        value.
+            value.

         @param title
             The caption to be displayed on the frame's title bar.
         @param pos
         @param title
             The caption to be displayed on the frame's title bar.
         @param pos

-            The window position. The value wxDefaultPosition indicates a default position,
-        chosen by
-            either the windowing system or wxWidgets, depending on platform.
+            The window position. The value @c wxDefaultPosition indicates a default position,
+            chosen by either the windowing system or wxWidgets, depending on platform.

         @param size
         @param size

-            The window size. The value wxDefaultSize indicates a default size, chosen by
+            The window size. The value @c wxDefaultSize indicates a default size, chosen by

             either the windowing system or wxWidgets, depending on platform.
         @param style
             The window style. See wxMDIChildFrame.
         @param name
             The name of the window. This parameter is used to associate a name with the
             either the windowing system or wxWidgets, depending on platform.
         @param style
             The window style. See wxMDIChildFrame.
         @param name
             The name of the window. This parameter is used to associate a name with the

-        item,
-            allowing the application user to set Motif resource values for
-            individual windows.
-
-        @remarks None.
+            item, allowing the application user to set Motif resource values for individual
+            windows.

 
         @see Create()
     */
 
         @see Create()
     */

-    wxMDIChildFrame();

     wxMDIChildFrame(wxMDIParentFrame* parent, wxWindowID id,
                     const wxString& title,
                     const wxPoint& pos = wxDefaultPosition,
                     const wxSize& size = wxDefaultSize,
                     long style = wxDEFAULT_FRAME_STYLE,
                     const wxString& name = "frame");
     wxMDIChildFrame(wxMDIParentFrame* parent, wxWindowID id,
                     const wxString& title,
                     const wxPoint& pos = wxDefaultPosition,
                     const wxSize& size = wxDefaultSize,
                     long style = wxDEFAULT_FRAME_STYLE,
                     const wxString& name = "frame");

-    //@}

 
     /**
         Destructor. Destroys all child windows and menu bar if present.
     */
 
     /**
         Destructor. Destroys all child windows and menu bar if present.
     */

-    ~wxMDIChildFrame();
+    virtual ~wxMDIChildFrame();

 
     /**
         Activates this MDI child frame.
 
         @see Maximize(), Restore()
     */
 
     /**
         Activates this MDI child frame.
 
         @see Maximize(), Restore()
     */

-    void Activate();
+    virtual void Activate();

 
     /**
 
     /**

-        Used in two-step frame construction. See wxMDIChildFrame()
-        for further details.
+        Used in two-step frame construction.
+        See wxMDIChildFrame() for further details.

     */
     bool Create(wxWindow* parent, wxWindowID id,
                 const wxString& title,
     */
     bool Create(wxWindow* parent, wxWindowID id,
                 const wxString& title,


@@ -400,6 +499,6 @@ public:
     /**
         Restores this MDI child frame (unmaximizes).
     */
     /**
         Restores this MDI child frame (unmaximizes).
     */

-    void Restore();
+    virtual void Restore();

 };
 
 };