// 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.
- @library{wxcore}
- @category{managedwnd}
-
@remarks
The client window is the area where MDI child windows exist. It doesn't have to
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
+ 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{managedwnd}
+
@see wxMDIChildFrame, wxMDIParentFrame, wxFrame
*/
class wxMDIClientWindow : public wxWindow
{
public:
-
/**
Default constructor.
- */
+
+ Objects of this class are only created by wxMDIParentFrame which uses
+ the default constructor and calls CreateClient() immediately
+ afterwards.
+ */
wxMDIClientWindow();
/**
- Constructor, creating the window.
+ 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. Currently unused.
+ The window style. Only wxHSCROLL and wxVSCROLL bits are meaningful
+ here.
- @remarks This constructor is called within wxMDIParentFrame::OnCreateClient().
-
- @see wxMDIParentFrame::wxMDIParentFrame(), wxMDIParentFrame::OnCreateClient()
- */
- wxMDIClientWindow(wxMDIParentFrame* parent, long style = 0);
-
- /**
- Destructor.
*/
- ~wxMDIClientWindow();
-
- /**
- 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
- 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.
+ 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.
- 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
+ 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.
- @beginStyleTable
- @style{wxCAPTION}
- Puts a caption on the frame.
- @style{wxDEFAULT_FRAME_STYLE}
- 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{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 @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
- Windows, it is implicit in @c 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.
@endStyleTable
@library{wxcore}
/**
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 @c 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 @c 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.
+ 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
- created. To use a different class from wxMDIClientWindow, override
- OnCreateClient().
+ @remarks
+
+ 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()
*/
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.
-
- 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
+ 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:
@code
frame = new MyParentFrame;
- frame->Create(parent, myParentFrameId, wxT("My Parent Frame"));
+ frame->Create(parent, myParentFrameId, "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.
+ 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. (Solutions to: julian.smart@btopenworld.com).
+ 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.
-
- @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.
-
- 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()
+ 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.
*/
- virtual void SetToolBar(wxWindow* toolbar);
+ virtual void SetWindowMenu(wxMenu* menu);
/**
- 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 @c wxFRAME_NO_WINDOW_MENU window style.
- */
- void SetWindowMenu(wxMenu* menu);
+ Tiles the MDI child windows either horizontally or vertically depending
+ on whether @a orient is @c wxHORIZONTAL or @c wxVERTICAL.
- /**
- 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.
- Currently only implemented for MSW, 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 @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}
- Displays the frame maximized (Windows only).
- @style{wxMAXIMIZE_BOX}
- Displays a maximize box on the frame (Windows and Motif only).
- @style{wxMINIMIZE}
- 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
- Windows, it is implicit in @c 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}
class wxMDIChildFrame : public wxFrame
{
public:
-
/**
Default constructor.
*/
@param title
The caption to be displayed on the frame's title bar.
@param pos
- The window position. The value @c wxDefaultPosition indicates a default position,
+ 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 @c 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.
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();
};
projects / wxWidgets.git / blobdiff