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