interface/wx/mdi.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        mdi.h
   3 // Purpose:     interface of wxMDIClientWindow
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxMDIClientWindow
  11
  12     An MDI client window is a child of wxMDIParentFrame, and manages zero or
  13     more wxMDIChildFrame objects.
  14
  15     @remarks
  16
  17     The client window is the area where MDI child windows exist. It doesn't have to
  18     cover the whole parent frame; other windows such as toolbars and a help window
  19     might coexist with it. There can be scrollbars on a client window, which are
  20     controlled by the parent window style.
  21
  22     The wxMDIClientWindow class is usually adequate without further derivation, and
  23     it is created automatically when the MDI parent frame is created. If the application
  24     needs to derive a new class, the function wxMDIParentFrame::OnCreateClient() must
  25     be overridden in order to give an opportunity to use a different class of client
  26     window.
  27
  28     Under Windows 95, the client window will automatically have a sunken border style
  29     when the active child is not maximized, and no border style when a child is maximized.
  30
  31     @library{wxcore}
  32     @category{managedwnd}
  33
  34     @see wxMDIChildFrame, wxMDIParentFrame, wxFrame
  35 */
  36 class wxMDIClientWindow : public wxWindow
  37 {
  38 public:
  39
  40     /**
  41         Default constructor.
  42     */
  43     wxMDIClientWindow();
  44
  45     /**
  46         Constructor, creating the window.
  47
  48         @param parent
  49             The window parent.
  50         @param style
  51             The window style. Currently unused.
  52
  53         @remarks This constructor is called within wxMDIParentFrame::OnCreateClient().
  54
  55         @see wxMDIParentFrame::wxMDIParentFrame(), wxMDIParentFrame::OnCreateClient()
  56     */
  57     wxMDIClientWindow(wxMDIParentFrame* parent, long style = 0);
  58
  59     /**
  60         Destructor.
  61     */
  62     virtual ~wxMDIClientWindow();
  63
  64     /**
  65         Used in two-step frame construction. See wxMDIClientWindow()
  66         for further details.
  67     */
  68     virtual bool CreateClient(wxMDIParentFrame* parent, long style = 0);
  69 };
  70
  71
  72
  73 /**
  74     @class wxMDIParentFrame
  75
  76     An MDI (Multiple Document Interface) parent frame is a window which can contain
  77     MDI child frames in its own 'desktop'. It is a convenient way to avoid window
  78     clutter, and is used in many popular Windows applications, such as Microsoft Word(TM).
  79
  80     @remarks
  81
  82     There may be multiple MDI parent frames in a single application, but this probably
  83     only makes sense within programming development environments.
  84
  85     Child frames may be of class wxMDIChildFrame (contained within the parent frame)
  86     or wxFrame (shown as a top-level frame).
  87
  88     An MDI parent frame always has a wxMDIClientWindow associated with it, which is the
  89     parent for MDI child frames. This client window may be resized to accommodate non-MDI
  90     windows, as seen in Microsoft Visual C++ (TM) and Microsoft Publisher (TM), where
  91     a documentation window is placed to one side of the workspace.
  92
  93     MDI remains popular despite dire warnings from Microsoft itself that MDI is an obsolete
  94     user interface style.
  95
  96     The implementation is native in Windows, and simulated under Motif. Under Motif, the
  97     child window frames will often have a different appearance from other frames because
  98     the window decorations are simulated.
  99
 100
 101     @beginStyleTable
 102     @style{wxCAPTION}
 103            Puts a caption on the frame.
 104     @style{wxDEFAULT_FRAME_STYLE}
 105            Defined as @c wxMINIMIZE_BOX | @c wxMAXIMIZE_BOX | @c wxTHICK_FRAME |
 106            @c wxSYSTEM_MENU | @c wxCAPTION.
 107     @style{wxHSCROLL}
 108            Displays a horizontal scrollbar in the client window, allowing the
 109            user to view child frames that are off the current view.
 110     @style{wxICONIZE}
 111            Display the frame iconized (minimized) (Windows only).
 112     @style{wxMAXIMIZE}
 113            Displays the frame maximized (Windows only).
 114     @style{wxMAXIMIZE_BOX}
 115            Displays a maximize box on the frame (Windows and Motif only).
 116     @style{wxMINIMIZE}
 117            Identical to @c wxICONIZE.
 118     @style{wxMINIMIZE_BOX}
 119            Displays a minimize box on the frame (Windows and Motif only).
 120     @style{wxRESIZE_BORDER}
 121            Displays a resizeable border around the window (Motif only; for
 122            Windows, it is implicit in @c wxTHICK_FRAME).
 123     @style{wxSTAY_ON_TOP}
 124            Stay on top of other windows (Windows only).
 125     @style{wxSYSTEM_MENU}
 126            Displays a system menu (Windows and Motif only).
 127     @style{wxTHICK_FRAME}
 128            Displays a thick frame around the window (Windows and Motif only).
 129     @style{wxVSCROLL}
 130            Displays a vertical scrollbar in the client window, allowing the
 131            user to view child frames that are off the current view.
 132     @style{wxFRAME_NO_WINDOW_MENU}
 133            Under Windows, removes the Window menu that is normally added
 134            automatically.
 135     @endStyleTable
 136
 137     @library{wxcore}
 138     @category{managedwnd}
 139
 140     @see wxMDIChildFrame, wxMDIClientWindow, wxFrame, wxDialog
 141 */
 142 class wxMDIParentFrame : public wxFrame
 143 {
 144 public:
 145
 146     /**
 147         Default constructor.
 148     */
 149     wxMDIParentFrame();
 150
 151     /**
 152         Constructor, creating the window.
 153
 154         @param parent
 155             The window parent. This should be @NULL.
 156         @param id
 157             The window identifier. It may take a value of -1 to indicate a default
 158             value.
 159         @param title
 160             The caption to be displayed on the frame's title bar.
 161         @param pos
 162             The window position. The value @c wxDefaultPosition indicates a default position,
 163             chosen by either the windowing system or wxWidgets, depending on platform.
 164         @param size
 165             The window size. The value @c wxDefaultSize indicates a default size, chosen by
 166             either the windowing system or wxWidgets, depending on platform.
 167         @param style
 168             The window style. See wxMDIParentFrame.
 169         @param name
 170             The name of the window. This parameter is used to associate a name
 171             with the item, allowing the application user to set Motif resource values
 172             for individual windows.
 173
 174         @remarks During the construction of the frame, the client window will be
 175                  created. To use a different class from wxMDIClientWindow, override
 176                  OnCreateClient().
 177                  Under Windows 95, the client window will automatically have a
 178                  sunken border style when the active child is not maximized,
 179                  and no border style when a child is maximized.
 180
 181         @see Create(), OnCreateClient()
 182     */
 183     wxMDIParentFrame(wxWindow* parent, wxWindowID id,
 184                      const wxString& title,
 185                      const wxPoint& pos = wxDefaultPosition,
 186                      const wxSize& size = wxDefaultSize,
 187                      long style = wxDEFAULT_FRAME_STYLE | wxVSCROLL | wxHSCROLL,
 188                      const wxString& name = "frame");
 189
 190     /**
 191         Destructor. Destroys all child windows and menu bar if present.
 192     */
 193     virtual ~wxMDIParentFrame();
 194
 195     /**
 196         Activates the MDI child following the currently active one.
 197
 198         @see ActivatePrevious()
 199     */
 200     virtual void ActivateNext();
 201
 202     /**
 203         Activates the MDI child preceding the currently active one.
 204
 205         @see ActivateNext()
 206     */
 207     virtual void ActivatePrevious();
 208
 209     /**
 210         Arranges any iconized (minimized) MDI child windows.
 211
 212         @see Cascade(), Tile()
 213     */
 214     virtual void ArrangeIcons();
 215
 216     /**
 217         Arranges the MDI child windows in a cascade.
 218
 219         @see Tile(), ArrangeIcons()
 220     */
 221     virtual void Cascade();
 222
 223     /**
 224         Used in two-step frame construction.
 225         See wxMDIParentFrame() for further details.
 226     */
 227     bool Create(wxWindow* parent, wxWindowID id,
 228                 const wxString& title,
 229                 const wxPoint& pos = wxDefaultPosition,
 230                 const wxSize& size = wxDefaultSize,
 231                 long style = wxDEFAULT_FRAME_STYLE | wxVSCROLL | wxHSCROLL,
 232                 const wxString& name = "frame");
 233
 234     /**
 235         Returns a pointer to the active MDI child, if there is one.
 236     */
 237     wxMDIChildFrame* GetActiveChild() const;
 238
 239     /**
 240         This gets the size of the frame 'client area' in pixels.
 241
 242         @param width
 243             Receives the client width in pixels.
 244         @param height
 245             Receives the client height in pixels.
 246
 247         @remarks
 248
 249         The client area is the area which may be drawn on by the programmer, excluding
 250         title bar, border, status bar, and toolbar if present.
 251
 252         If you wish to manage your own toolbar (or perhaps you have more than one),
 253         provide an @b OnSize event handler. Call GetClientSize() to find how much space
 254         there is for your windows and don't forget to set the size and position of
 255         the MDI client window as well as your toolbar and other windows (but not the
 256         status bar).
 257
 258         If you have set a toolbar with wxMDIParentFrame::SetToolbar(), the client size
 259         returned will have subtracted the toolbar height. However, the available positions
 260         for the client window and other windows of the frame do not start at zero - you
 261         must add the toolbar height.
 262
 263         The position and size of the status bar and toolbar (if known to the frame) are
 264         always managed by wxMDIParentFrame, regardless of what behaviour is defined in
 265         your @b OnSize event handler. However, the client window position and size are always
 266         set in @b OnSize, so if you override this event handler, make sure you deal with the
 267         client window.
 268
 269         You do not have to manage the size and position of MDI child windows, since they
 270         are managed automatically by the client window.
 271
 272         @see GetToolBar(), SetToolBar(), wxMDIClientWindow
 273
 274         @beginWxPythonOnly
 275         The wxPython version of this method takes no arguments and returns a tuple containing
 276         width and height.
 277         @endWxPythonOnly
 278     */
 279     void GetClientSize(int* width, int* height) const;
 280
 281     /**
 282         Returns a pointer to the client window.
 283
 284         @see OnCreateClient()
 285     */
 286     wxMDIClientWindow* GetClientWindow() const;
 287
 288     /**
 289         Returns the window being used as the toolbar for this frame.
 290
 291         @see SetToolBar()
 292     */
 293     virtual wxWindow* GetToolBar() const;
 294
 295     /**
 296         Returns the current Window menu (added by wxWidgets to the menubar). This
 297         function
 298         is available under Windows only.
 299     */
 300     wxMenu* GetWindowMenu() const;
 301
 302     /**
 303         Override this to return a different kind of client window. If you override this
 304         function, you must create your parent frame in two stages, or your function will
 305         never be called, due to the way C++ treats virtual functions called from constructors.
 306         For example:
 307
 308         @code
 309         frame = new MyParentFrame;
 310         frame->Create(parent, myParentFrameId, wxT("My Parent Frame"));
 311         @endcode
 312
 313         @remarks
 314
 315         You might wish to derive from wxMDIClientWindow in order to implement different
 316         erase behaviour, for example, such as painting a bitmap on the background.
 317
 318         Note that it is probably impossible to have a client window that scrolls
 319         as well as painting a bitmap or pattern, since in @b OnScroll, the scrollbar
 320         positions always return zero.
 321
 322         @see GetClientWindow(), wxMDIClientWindow
 323     */
 324     virtual wxMDIClientWindow* OnCreateClient();
 325
 326     /**
 327         Sets the window to be used as a toolbar for this
 328         MDI parent window. It saves the application having to manage the positioning
 329         of the toolbar MDI client window.
 330
 331         @param toolbar
 332             Toolbar to manage.
 333
 334         @remarks
 335
 336         When the frame is resized, the toolbar is resized to be the width of the frame
 337         client area, and the toolbar height is kept the same.
 338
 339         When the frame is resized, the toolbar is resized to be the width of the frame
 340         client area, and the toolbar height is kept the same.
 341
 342         The parent of the toolbar must be this frame.
 343
 344         If you wish to manage your own toolbar (or perhaps you have more than one),
 345         don't call this function, and instead manage your subwindows and the MDI client
 346         window by providing an @b OnSize event handler. Call wxMDIParentFrame::GetClientSize()
 347         to find how much space there is for your windows.
 348
 349         Note that SDI (normal) frames and MDI child windows must always have their toolbars
 350         managed by the application.
 351
 352         @see GetToolBar(), GetClientSize()
 353     */
 354     virtual void SetToolBar(wxWindow* toolbar);
 355
 356     /**
 357         Call this to change the current Window menu.
 358         Ownership of the menu object passes to the frame when you call this function.
 359
 360         This call is available under Windows only.
 361
 362         To remove the window completely, use the @c wxFRAME_NO_WINDOW_MENU window style.
 363     */
 364     void SetWindowMenu(wxMenu* menu);
 365
 366     /**
 367         Tiles the MDI child windows either horizontally or vertically depending on
 368         whether @a orient is @c wxHORIZONTAL or @c wxVERTICAL.
 369
 370         Currently only implemented for MSW, does nothing under the other platforms.
 371     */
 372     virtual void Tile(wxOrientation orient = wxHORIZONTAL);
 373 };
 374
 375
 376
 377 /**
 378     @class wxMDIChildFrame
 379
 380     An MDI child frame is a frame that can only exist on a wxMDIClientWindow,
 381     which is itself a child of wxMDIParentFrame.
 382
 383     @beginStyleTable
 384     @style{wxCAPTION}
 385            Puts a caption on the frame.
 386     @style{wxDEFAULT_FRAME_STYLE}
 387            Defined as @c wxMINIMIZE_BOX | @c wxMAXIMIZE_BOX | @c wxTHICK_FRAME |
 388            @c wxSYSTEM_MENU | @c wxCAPTION.
 389     @style{wxICONIZE}
 390            Display the frame iconized (minimized) (Windows only).
 391     @style{wxMAXIMIZE}
 392            Displays the frame maximized (Windows only).
 393     @style{wxMAXIMIZE_BOX}
 394            Displays a maximize box on the frame (Windows and Motif only).
 395     @style{wxMINIMIZE}
 396            Identical to @c wxICONIZE.
 397     @style{wxMINIMIZE_BOX}
 398            Displays a minimize box on the frame (Windows and Motif only).
 399     @style{wxRESIZE_BORDER}
 400            Displays a resizeable border around the window (Motif only; for
 401            Windows, it is implicit in @c wxTHICK_FRAME).
 402     @style{wxSTAY_ON_TOP}
 403            Stay on top of other windows (Windows only).
 404     @style{wxSYSTEM_MENU}
 405            Displays a system menu (Windows and Motif only).
 406     @style{wxTHICK_FRAME}
 407            Displays a thick frame around the window (Windows and Motif only).
 408     @endStyleTable
 409
 410     @remarks
 411     Although internally an MDI child frame is a child of the MDI client window,
 412     in wxWidgets you create it as a child of wxMDIParentFrame.
 413     You can usually forget that the client window exists.
 414     MDI child frames are clipped to the area of the MDI client window, and may
 415     be iconized on the client window.
 416     You can associate a menubar with a child frame as usual, although an MDI
 417     child doesn't display its menubar under its own title bar.
 418     The MDI parent frame's menubar will be changed to reflect the currently
 419     active child frame.
 420     If there are currently no children, the parent frame's own menubar will
 421     be displayed.
 422
 423     @library{wxcore}
 424     @category{managedwnd}
 425
 426     @see wxMDIClientWindow, wxMDIParentFrame, wxFrame
 427 */
 428 class wxMDIChildFrame : public wxFrame
 429 {
 430 public:
 431
 432     /**
 433         Default constructor.
 434     */
 435     wxMDIChildFrame();
 436
 437     /**
 438         Constructor, creating the window.
 439
 440         @param parent
 441             The window parent. This should not be @NULL.
 442         @param id
 443             The window identifier. It may take a value of -1 to indicate a default
 444             value.
 445         @param title
 446             The caption to be displayed on the frame's title bar.
 447         @param pos
 448             The window position. The value @c wxDefaultPosition indicates a default position,
 449             chosen by either the windowing system or wxWidgets, depending on platform.
 450         @param size
 451             The window size. The value @c wxDefaultSize indicates a default size, chosen by
 452             either the windowing system or wxWidgets, depending on platform.
 453         @param style
 454             The window style. See wxMDIChildFrame.
 455         @param name
 456             The name of the window. This parameter is used to associate a name with the
 457             item, allowing the application user to set Motif resource values for individual
 458             windows.
 459
 460         @see Create()
 461     */
 462     wxMDIChildFrame(wxMDIParentFrame* parent, wxWindowID id,
 463                     const wxString& title,
 464                     const wxPoint& pos = wxDefaultPosition,
 465                     const wxSize& size = wxDefaultSize,
 466                     long style = wxDEFAULT_FRAME_STYLE,
 467                     const wxString& name = "frame");
 468
 469     /**
 470         Destructor. Destroys all child windows and menu bar if present.
 471     */
 472     virtual ~wxMDIChildFrame();
 473
 474     /**
 475         Activates this MDI child frame.
 476
 477         @see Maximize(), Restore()
 478     */
 479     virtual void Activate();
 480
 481     /**
 482         Used in two-step frame construction.
 483         See wxMDIChildFrame() for further details.
 484     */
 485     bool Create(wxWindow* parent, wxWindowID id,
 486                 const wxString& title,
 487                 const wxPoint& pos = wxDefaultPosition,
 488                 const wxSize& size = wxDefaultSize,
 489                 long style = wxDEFAULT_FRAME_STYLE,
 490                 const wxString& name = "frame");
 491
 492     /**
 493         Maximizes this MDI child frame.
 494
 495         @see Activate(), Restore()
 496     */
 497     void Maximize(bool maximize);
 498
 499     /**
 500         Restores this MDI child frame (unmaximizes).
 501     */
 502     virtual void Restore();
 503 };
 504