]> git.saurik.com Git - wxWidgets.git/blobdiff - interface/wx/mdi.h
added the possibility to rescale the image during loading, especially useful with...
[wxWidgets.git] / interface / wx / mdi.h
index 3d5f3b80bc95cc280f115f71f2b03dcab8b576a1..0729f366f5e0d2bf090ba5cac62e75885daa53cd 100644 (file)
 
 /**
     @class wxMDIClientWindow
-    @wxheader{mdi.h}
 
     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}
-    @category{FIXME}
+    @category{managedwnd}
 
     @see wxMDIChildFrame, wxMDIParentFrame, wxFrame
 */
 class wxMDIClientWindow : public wxWindow
 {
 public:
-    //@{
     /**
-        Constructor, creating the window.
-
-        @param parent
-            The window parent.
-        @param style
-            The window style. Currently unused.
-
-        @remarks The second style of constructor is called within
-                 wxMDIParentFrame::OnCreateClient.
+        Default constructor.
 
-        @see wxMDIParentFrame::wxMDIParentFrame, wxMDIParentFrame::OnCreateClient
-    */
+        Objects of this class are only created by wxMDIParentFrame which uses
+        the default constructor and calls CreateClient() immediately
+        afterwards.
+     */
     wxMDIClientWindow();
-    wxMDIClientWindow(wxMDIParentFrame* parent, long style = 0);
-    //@}
 
     /**
-        Destructor.
-    */
-    ~wxMDIClientWindow();
+        Called by wxMDIParentFrame immediately after creating the client
+        window.
+
+        This function may be overridden in the derived class but the base class
+        version must usually be called first to really create the window.
+
+        @param parent
+            The window parent.
+        @param style
+            The window style. Only wxHSCROLL and wxVSCROLL bits are meaningful
+            here.
 
-    /**
-        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
-    @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
-    clutter,
-    and is used in many popular Windows applications, such as Microsoft Word(TM).
+    An MDI (Multiple Document Interface) parent frame is a window which can
+    contain MDI child frames in its client area which emulates the full
+    desktop.
+
+    MDI is a user-interface model in which all the window reside inside the
+    single parent window as opposed to being separate from each other. It
+    remains popular despite dire warnings from Microsoft itself (which
+    popularized this model in the first model) that MDI is obsolete.
+
+    An MDI parent frame always has a wxMDIClientWindow associated with it,
+    which is the parent for MDI child frames. In the simplest case, the client
+    window takes up the entire parent frame area but it is also possible to
+    resize it to be smaller in order to have other windows in the frame, a
+    typical example is using a sidebar along one of the window edges.
+
+    The appearance of MDI applications differs between different ports. The
+    classic MDI model, with child windows which can be independently moved,
+    resized etc, is only available under MSW, which provides native support for
+    it. In Mac ports, multiple top level windows are used for the MDI children
+    too and the MDI parent frame itself is invisible, to accommodate the native
+    look and feel requirements. In all the other ports, a tab-based MDI
+    implementation (sometimes called TDI) is used and so at most one MDI child
+    is visible at any moment (child frames are always maximized).
+
+    @remarks
+
+    Although it is possible to have multiple MDI parent frames, a typical MDI
+    application has a single MDI parent frame window inside which multiple MDI
+    child frames, i.e. objects of class wxMDIChildFrame, can be created.
+
 
     @beginStyleTable
-    @style{wxCAPTION}
-           Puts a caption on the frame.
-    @style{wxDEFAULT_FRAME_STYLE}
-           Defined as wxMINIMIZE_BOX |  wxMAXIMIZE_BOX |  wxTHICK_FRAME |
-           wxSYSTEM_MENU |  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{wxICONIZE}
-           Display the frame iconized (minimized) (Windows only).
-    @style{wxMAXIMIZE}
-           Displays the frame maximized (Windows only).
-    @style{wxMAXIMIZE_BOX}
-           Displays a maximize box on the frame (Windows and Motif only).
-    @style{wxMINIMIZE}
-           Identical to 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
-           Windows, it is implicit in wxTHICK_FRAME).
-    @style{wxSTAY_ON_TOP}
-           Stay on top of other windows (Windows only).
-    @style{wxSYSTEM_MENU}
-           Displays a system menu (Windows and Motif only).
-    @style{wxTHICK_FRAME}
-           Displays a thick frame around the window (Windows and Motif only).
-    @style{wxVSCROLL}
-           Displays a vertical scrollbar in the client window, allowing the
-           user to view child frames that are off the current view.
-    @style{wxFRAME_NO_WINDOW_MENU}
-           Under Windows, removes the Window menu that is normally added
-           automatically.
+
+    There are no special styles for this class, all wxFrame styles apply to it
+    in the usual way. The only exception is that wxHSCROLL and wxVSCROLL styles
+    apply not to the frame itself but to the client window, so that using them
+    enables horizontal and vertical scrollbars for this window and not the
+    frame.
+
     @endStyleTable
 
     @library{wxcore}
@@ -106,220 +116,242 @@ public:
 class wxMDIParentFrame : public wxFrame
 {
 public:
-    //@{
+
+    /**
+        Default constructor.
+
+        Use Create() for the objects created using this constructor.
+    */
+    wxMDIParentFrame();
+
     /**
         Constructor, creating the window.
 
+        Notice that if you override virtual OnCreateClient() method you
+        shouldn't be using this constructor but the default constructor and
+        Create() as otherwise your overridden method is never going to be
+        called because of the usual C++ virtual call resolution rules.
+
         @param parent
-            The window parent. This should be @NULL.
+            The window parent. Usually is @NULL.
         @param id
-            The window identifier. It may take a value of -1 to indicate a default
-        value.
+            The window identifier. It may take a value of @c wxID_ANY to
+            indicate a default value.
         @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
-            The window size. The value wxDefaultSize indicates a default size, chosen by
-            either the windowing system or wxWidgets, depending on platform.
+            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.
+            The window style. Default value includes wxHSCROLL and wxVSCROLL
+            styles.
         @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
 
-        @remarks During the construction of the frame, the client window will be
-                 created. To use a different class from
-                 wxMDIClientWindow, override
-                 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()
     */
-    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");
-    //@}
+                     const wxString& name = wxFrameNameStr);
 
     /**
-        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.
 
+        The MDI children are maintained in an ordered list and this function
+        switches to the next element in this list, wrapping around the end of
+        it if the currently active child is the last one.
+
         @see ActivatePrevious()
     */
-    void ActivateNext();
+    virtual void ActivateNext();
 
     /**
         Activates the MDI child preceding the currently active one.
 
         @see ActivateNext()
     */
-    void ActivatePrevious();
+    virtual void ActivatePrevious();
 
     /**
         Arranges any iconized (minimized) MDI child windows.
 
+        This method is only implemented in MSW MDI implementation and does
+        nothing under the other platforms.
+
         @see Cascade(), Tile()
     */
-    void ArrangeIcons();
+    virtual void ArrangeIcons();
 
     /**
         Arranges the MDI child windows in a cascade.
 
+        This method is only implemented in MSW MDI implementation and does
+        nothing under the other platforms.
+
         @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,
+    bool Create(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");
+                const wxString& name = wxFrameNameStr);
 
     /**
         Returns a pointer to the active MDI child, if there is one.
-    */
-    wxMDIChildFrame* GetActiveChild() const;
 
-    /**
-        This gets the size of the frame 'client area' in pixels.
-
-        @param width
-            Receives the client width 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.
-
-        @see GetToolBar(), SetToolBar(),
-             wxMDIClientWindow
+        If there are any children at all this function returns a non-@NULL
+        pointer.
     */
-    virtual void GetClientSize(int* width, int* height) const;
+    virtual wxMDIChildFrame* GetActiveChild() const;
 
     /**
         Returns a pointer to the client window.
 
         @see OnCreateClient()
     */
-    wxMDIClientWindow* GetClientWindow() const;
+    wxMDIClientWindowBase* GetClientWindow() const;
 
     /**
-        Returns the window being used as the toolbar for this frame.
+        Returns the current MDI Window menu.
+
+        Unless wxFRAME_NO_WINDOW_MENU style was used, a default menu listing
+        all the currently active children and providing the usual operations
+        (tile, cascade, ...) on them is created automatically by the library
+        and this function can be used to retrieve it. Notice that the default
+        menu can be replaced by calling SetWindowMenu().
 
-        @see SetToolBar()
+        This function is currently not available under OS X.
+
+        @return The current Window menu or @NULL.
     */
-    virtual wxWindow* GetToolBar() const;
+    wxMenu *GetWindowMenu() const;
 
     /**
-        Returns the current Window menu (added by wxWidgets to the menubar). This
-        function
-        is available under Windows only.
-    */
-    wxMenu* GetWindowMenu() const;
+        Returns whether the MDI implementation is tab-based.
+
+        Currently only the MSW port uses the real MDI. In Mac ports the usual
+        SDI is used, as common under this platforms, and all the other ports
+        use TDI implementation.
+
+        TDI-based MDI applications have different appearance and functionality
+        (e.g. child frames can't be minimized and only one of them is visible
+        at any given time) so the application may need to adapt its interface
+        somewhat depending on the return value of this function.
+     */
+    static bool IsTDI();
 
     /**
-        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:
+        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:
 
-        @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.
+        @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.
+
+        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
     */
     virtual wxMDIClientWindow* OnCreateClient();
 
     /**
-        Sets the window to be used as a toolbar for this
-        MDI parent window. It saves the application having to manage the positioning
-        of the toolbar MDI client window.
+        Replace the current MDI Window menu.
 
-        @param toolbar
-            Toolbar to manage.
+        Ownership of the menu object passes to the frame when you call this
+        function, i.e. the menu will be deleted by it when it's no longer
+        needed (usually when the frame itself is deleted or when
+        SetWindowMenu() is called again).
 
-        @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.
+        To remove the window completely, you can use the wxFRAME_NO_WINDOW_MENU
+        window style but this function also allows to do it by passing @NULL
+        pointer as @a menu.
 
-        @see GetToolBar(), GetClientSize()
-    */
-    virtual void SetToolBar(wxWindow* toolbar);
+        This function is currently not available under OS X.
 
-    /**
-        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.
-        To remove the window completely, use the wxFRAME_NO_WINDOW_MENU window style.
+        @param menu
+            The menu to be used instead of the standard MDI Window menu or @NULL.
     */
-    void SetWindowMenu(wxMenu* menu);
+    virtual void SetWindowMenu(wxMenu* menu);
 
     /**
-        Tiles the MDI child windows either horizontally or vertically depending on
-        whether @a orient is wxHORIZONTAL or wxVERTICAL.
-        Currently only implemented for MSW, does nothing under the other platforms.
+        Tiles the MDI child windows either horizontally or vertically depending
+        on whether @a orient is @c wxHORIZONTAL or @c wxVERTICAL.
+
+        This method is only implemented in MSW MDI implementation and does
+        nothing under the other platforms.
+
     */
-    void Tile(wxOrientation orient = wxHORIZONTAL);
+    virtual void Tile(wxOrientation orient = wxHORIZONTAL);
 };
 
 
 
 /**
     @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 inside a
+    wxMDIClientWindow, which is itself a child of wxMDIParentFrame.
 
     @beginStyleTable
-    @style{wxCAPTION}
-           Puts a caption on the frame.
-    @style{wxDEFAULT_FRAME_STYLE}
-           Defined as wxMINIMIZE_BOX |  wxMAXIMIZE_BOX |  wxTHICK_FRAME |
-           wxSYSTEM_MENU |  wxCAPTION.
-    @style{wxICONIZE}
-           Display the frame iconized (minimized) (Windows only).
-    @style{wxMAXIMIZE}
-           Displays the frame maximized (Windows only).
-    @style{wxMAXIMIZE_BOX}
-           Displays a maximize box on the frame (Windows and Motif only).
-    @style{wxMINIMIZE}
-           Identical to 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
-           Windows, it is implicit in wxTHICK_FRAME).
-    @style{wxSTAY_ON_TOP}
-           Stay on top of other windows (Windows only).
-    @style{wxSYSTEM_MENU}
-           Displays a system menu (Windows and Motif only).
-    @style{wxTHICK_FRAME}
-           Displays a thick frame around the window (Windows and Motif only).
+    All of the standard wxFrame styles can be used but most of them are ignored
+    by TDI-based MDI implementations.
     @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. In fact, 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}
 
@@ -328,7 +360,11 @@ public:
 class wxMDIChildFrame : public wxFrame
 {
 public:
-    //@{
+    /**
+        Default constructor.
+    */
+    wxMDIChildFrame();
+
     /**
         Constructor, creating the window.
 
@@ -336,70 +372,89 @@ 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
-        value.
+            value.
         @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
-            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
-        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()
     */
-    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");
-    //@}
+                    const wxString& name = wxFrameNameStr);
 
     /**
         Destructor. Destroys all child windows and menu bar if present.
     */
-    ~wxMDIChildFrame();
+    virtual ~wxMDIChildFrame();
 
     /**
         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(wxMDIParentFrame* parent, wxWindowID id, const wxString& title,
                 const wxPoint& pos = wxDefaultPosition,
                 const wxSize& size = wxDefaultSize,
                 long style = wxDEFAULT_FRAME_STYLE,
-                const wxString& name = "frame");
+                const wxString& name = wxFrameNameStr);
+
+    /**
+        Returns the MDI parent frame containing this child.
+
+        Notice that this may return a different object than GetParent() as the
+        child frames may be created as children of the client window
+        internally.
+     */
+    wxMDIParentFrame *GetMDIParent() const;
+
+    /**
+        Returns true for MDI children in TDI implementations.
+
+        TDI-based implementations represent MDI children as pages in a
+        wxNotebook and so they are always maximized and can't be restored or
+        iconized.
+
+        @see wxMDIParentFrame::IsTDI().
+     */
+    virtual bool IsAlwaysMaximized() const;
 
     /**
         Maximizes this MDI child frame.
 
+        This function doesn't do anything if IsAlwaysMaximized() returns @true.
+
         @see Activate(), Restore()
     */
-    void Maximize(bool maximize);
+    virtual void Maximize(bool maximize = true);
 
     /**
         Restores this MDI child frame (unmaximizes).
+
+        This function doesn't do anything if IsAlwaysMaximized() returns @true.
+
+        @see Activate(), Maximize()
     */
-    void Restore();
+    virtual void Restore();
 };