X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/ae3c17b4013e80b99976c750c19fca47729517f6..b8737371e220ef1920e6a3d2aed88c4bc2b04daf:/interface/wx/mdi.h diff --git a/interface/wx/mdi.h b/interface/wx/mdi.h index 3d5f3b80bc..35334c364f 100644 --- a/interface/wx/mdi.h +++ b/interface/wx/mdi.h @@ -3,99 +3,109 @@ // Purpose: interface of wxMDIClientWindow // Author: wxWidgets team // RCS-ID: $Id$ -// Licence: wxWindows license +// Licence: wxWindows licence ///////////////////////////////////////////////////////////////////////////// /** @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 wxMSW, 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,253 @@ 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 ::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 ::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 wxMSW, 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. - @see SetToolBar() - */ - virtual wxWindow* GetToolBar() const; + 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(). - /** - Returns the current Window menu (added by wxWidgets to the menubar). This - function - is available under Windows only. + This function is currently not available under OS X. + + @return The current Window menu or @NULL. */ - wxMenu* GetWindowMenu() const; + wxMenu *GetWindowMenu() const; /** - 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: + Returns whether the MDI implementation is tab-based. - @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. + 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. - @see GetClientWindow(), wxMDIClientWindow - */ - virtual wxMDIClientWindow* OnCreateClient(); + 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(); /** - 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. + Override this to return a different kind of client window. - @param toolbar - Toolbar to manage. + 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 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. + @code + frame = new MyParentFrame; + frame->Create(parent, myParentFrameId, "My Parent Frame"); + @endcode - @see GetToolBar(), GetClientSize() + @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 void SetToolBar(wxWindow* toolbar); + virtual wxMDIClientWindow* OnCreateClient(); /** - 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. + Replace the current MDI Window menu. + + 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). + + 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. + + The menu may include the items with the following standard identifiers + (but may use arbitrary text and help strings and bitmaps for them): + - @c wxID_MDI_WINDOW_CASCADE + - @c wxID_MDI_WINDOW_TILE_HORZ + - @c wxID_MDI_WINDOW_TILE_VERT + - @c wxID_MDI_WINDOW_ARRANGE_ICONS + - @c wxID_MDI_WINDOW_PREV + - @c wxID_MDI_WINDOW_NEXT + All of which are handled by wxMDIParentFrame itself. If any other + commands are used in the menu, the derived frame should handle them. + + This function is currently not available under OS X. + + @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 +371,11 @@ public: class wxMDIChildFrame : public wxFrame { public: - //@{ + /** + Default constructor. + */ + wxMDIChildFrame(); + /** Constructor, creating the window. @@ -336,70 +383,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 ::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 ::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(); };