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, const wxString& title,
 228                 const wxPoint& pos = wxDefaultPosition,
 229                 const wxSize& size = wxDefaultSize, long style = wxDEFAULT_FRAME_STYLE | wxVSCROLL | wxHSCROLL,
 230                 const wxString& name = wxFrameNameStr);
 231
 232     /**
 233         Returns a pointer to the active MDI child, if there is one.
 234     */
 235     wxMDIChildFrame* GetActiveChild() const;
 236
 237     /**
 238         This gets the size of the frame 'client area' in pixels.
 239
 240         @param width
 241             Receives the client width in pixels.
 242         @param height
 243             Receives the client height in pixels.
 244
 245         @remarks
 246
 247         The client area is the area which may be drawn on by the programmer, excluding
 248         title bar, border, status bar, and toolbar if present.
 249
 250         If you wish to manage your own toolbar (or perhaps you have more than one),
 251         provide an @b OnSize event handler. Call GetClientSize() to find how much space
 252         there is for your windows and don't forget to set the size and position of
 253         the MDI client window as well as your toolbar and other windows (but not the
 254         status bar).
 255
 256         If you have set a toolbar with wxMDIParentFrame::SetToolbar(), the client size
 257         returned will have subtracted the toolbar height. However, the available positions
 258         for the client window and other windows of the frame do not start at zero - you
 259         must add the toolbar height.
 260
 261         The position and size of the status bar and toolbar (if known to the frame) are
 262         always managed by wxMDIParentFrame, regardless of what behaviour is defined in
 263         your @b OnSize event handler. However, the client window position and size are always
 264         set in @b OnSize, so if you override this event handler, make sure you deal with the
 265         client window.
 266
 267         You do not have to manage the size and position of MDI child windows, since they
 268         are managed automatically by the client window.
 269
 270         @see GetToolBar(), SetToolBar(), wxMDIClientWindow
 271
 272         @beginWxPythonOnly
 273         The wxPython version of this method takes no arguments and returns a tuple containing
 274         width and height.
 275         @endWxPythonOnly
 276     */
 277     void GetClientSize(int* width, int* height) const;
 278
 279     /**
 280         Returns a pointer to the client window.
 281
 282         @see OnCreateClient()
 283     */
 284     wxMDIClientWindow* GetClientWindow() const;
 285
 286     /**
 287         Returns the window being used as the toolbar for this frame.
 288
 289         @see SetToolBar()
 290     */
 291     virtual wxToolBar* GetToolBar() const;
 292
 293     /**
 294         Returns the current Window menu (added by wxWidgets to the menubar). This
 295         function
 296         is available under Windows only.
 297     */
 298     wxMenu* GetWindowMenu() const;
 299
 300     /**
 301         Override this to return a different kind of client window. If you override this
 302         function, you must create your parent frame in two stages, or your function will
 303         never be called, due to the way C++ treats virtual functions called from constructors.
 304         For example:
 305
 306         @code
 307         frame = new MyParentFrame;
 308         frame->Create(parent, myParentFrameId, wxT("My Parent Frame"));
 309         @endcode
 310
 311         @remarks
 312
 313         You might wish to derive from wxMDIClientWindow in order to implement different
 314         erase behaviour, for example, such as painting a bitmap on the background.
 315
 316         Note that it is probably impossible to have a client window that scrolls
 317         as well as painting a bitmap or pattern, since in @b OnScroll, the scrollbar
 318         positions always return zero.
 319
 320         @see GetClientWindow(), wxMDIClientWindow
 321     */
 322     virtual wxMDIClientWindow* OnCreateClient();
 323
 324     /**
 325         Sets the window to be used as a toolbar for this
 326         MDI parent window. It saves the application having to manage the positioning
 327         of the toolbar MDI client window.
 328
 329         @param toolbar
 330             Toolbar to manage.
 331
 332         @remarks
 333
 334         When the frame is resized, the toolbar is resized to be the width of the frame
 335         client area, and the toolbar height is kept the same.
 336
 337         When the frame is resized, the toolbar is resized to be the width of the frame
 338         client area, and the toolbar height is kept the same.
 339
 340         The parent of the toolbar must be this frame.
 341
 342         If you wish to manage your own toolbar (or perhaps you have more than one),
 343         don't call this function, and instead manage your subwindows and the MDI client
 344         window by providing an @b OnSize event handler. Call wxMDIParentFrame::GetClientSize()
 345         to find how much space there is for your windows.
 346
 347         Note that SDI (normal) frames and MDI child windows must always have their toolbars
 348         managed by the application.
 349
 350         @see GetToolBar(), GetClientSize()
 351     */
 352     virtual void SetToolBar(wxToolBar* toolbar);
 353
 354     /**
 355         Call this to change the current Window menu.
 356         Ownership of the menu object passes to the frame when you call this function.
 357
 358         This call is available under Windows only.
 359
 360         To remove the window completely, use the @c wxFRAME_NO_WINDOW_MENU window style.
 361     */
 362     void SetWindowMenu(wxMenu* menu);
 363
 364     /**
 365         Tiles the MDI child windows either horizontally or vertically depending on
 366         whether @a orient is @c wxHORIZONTAL or @c wxVERTICAL.
 367
 368         Currently only implemented for MSW, does nothing under the other platforms.
 369     */
 370     virtual void Tile(wxOrientation orient = wxHORIZONTAL);
 371 };
 372
 373
 374
 375 /**
 376     @class wxMDIChildFrame
 377
 378     An MDI child frame is a frame that can only exist on a wxMDIClientWindow,
 379     which is itself a child of wxMDIParentFrame.
 380
 381     @beginStyleTable
 382     @style{wxCAPTION}
 383            Puts a caption on the frame.
 384     @style{wxDEFAULT_FRAME_STYLE}
 385            Defined as @c wxMINIMIZE_BOX | @c wxMAXIMIZE_BOX | @c wxTHICK_FRAME |
 386            @c wxSYSTEM_MENU | @c wxCAPTION.
 387     @style{wxICONIZE}
 388            Display the frame iconized (minimized) (Windows only).
 389     @style{wxMAXIMIZE}
 390            Displays the frame maximized (Windows only).
 391     @style{wxMAXIMIZE_BOX}
 392            Displays a maximize box on the frame (Windows and Motif only).
 393     @style{wxMINIMIZE}
 394            Identical to @c wxICONIZE.
 395     @style{wxMINIMIZE_BOX}
 396            Displays a minimize box on the frame (Windows and Motif only).
 397     @style{wxRESIZE_BORDER}
 398            Displays a resizeable border around the window (Motif only; for
 399            Windows, it is implicit in @c wxTHICK_FRAME).
 400     @style{wxSTAY_ON_TOP}
 401            Stay on top of other windows (Windows only).
 402     @style{wxSYSTEM_MENU}
 403            Displays a system menu (Windows and Motif only).
 404     @style{wxTHICK_FRAME}
 405            Displays a thick frame around the window (Windows and Motif only).
 406     @endStyleTable
 407
 408     @remarks
 409     Although internally an MDI child frame is a child of the MDI client window,
 410     in wxWidgets you create it as a child of wxMDIParentFrame.
 411     You can usually forget that the client window exists.
 412     MDI child frames are clipped to the area of the MDI client window, and may
 413     be iconized on the client window.
 414     You can associate a menubar with a child frame as usual, although an MDI
 415     child doesn't display its menubar under its own title bar.
 416     The MDI parent frame's menubar will be changed to reflect the currently
 417     active child frame.
 418     If there are currently no children, the parent frame's own menubar will
 419     be displayed.
 420
 421     @library{wxcore}
 422     @category{managedwnd}
 423
 424     @see wxMDIClientWindow, wxMDIParentFrame, wxFrame
 425 */
 426 class wxMDIChildFrame : public wxFrame
 427 {
 428 public:
 429
 430     /**
 431         Default constructor.
 432     */
 433     wxMDIChildFrame();
 434
 435     /**
 436         Constructor, creating the window.
 437
 438         @param parent
 439             The window parent. This should not be @NULL.
 440         @param id
 441             The window identifier. It may take a value of -1 to indicate a default
 442             value.
 443         @param title
 444             The caption to be displayed on the frame's title bar.
 445         @param pos
 446             The window position. The value @c wxDefaultPosition indicates a default position,
 447             chosen by either the windowing system or wxWidgets, depending on platform.
 448         @param size
 449             The window size. The value @c wxDefaultSize indicates a default size, chosen by
 450             either the windowing system or wxWidgets, depending on platform.
 451         @param style
 452             The window style. See wxMDIChildFrame.
 453         @param name
 454             The name of the window. This parameter is used to associate a name with the
 455             item, allowing the application user to set Motif resource values for individual
 456             windows.
 457
 458         @see Create()
 459     */
 460     wxMDIChildFrame(wxMDIParentFrame* parent, wxWindowID id,
 461                     const wxString& title,
 462                     const wxPoint& pos = wxDefaultPosition,
 463                     const wxSize& size = wxDefaultSize,
 464                     long style = wxDEFAULT_FRAME_STYLE,
 465                     const wxString& name = "frame");
 466
 467     /**
 468         Destructor. Destroys all child windows and menu bar if present.
 469     */
 470     virtual ~wxMDIChildFrame();
 471
 472     /**
 473         Activates this MDI child frame.
 474
 475         @see Maximize(), Restore()
 476     */
 477     virtual void Activate();
 478
 479     /**
 480         Used in two-step frame construction.
 481         See wxMDIChildFrame() for further details.
 482     */
 483     bool Create(wxMDIParentFrame* parent, wxWindowID id, const wxString& title,
 484                 const wxPoint& pos = wxDefaultPosition,
 485                 const wxSize& size = wxDefaultSize,
 486                 long style = wxDEFAULT_FRAME_STYLE,
 487                 const wxString& name = wxFrameNameStr);
 488
 489     /**
 490         Maximizes this MDI child frame.
 491
 492         @see Activate(), Restore()
 493     */
 494     virtual void Maximize(bool maximize = true);
 495
 496     /**
 497         Restores this MDI child frame (unmaximizes).
 498     */
 499     virtual void Restore();
 500 };
 501