interface/wx/mdi.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        mdi.h
   3 // Purpose:     interface of wxMDIClientWindow
   4 // Author:      wxWidgets team
   5 // Licence:     wxWindows licence
   6 /////////////////////////////////////////////////////////////////////////////
   7
   8 /**
   9     @class wxMDIClientWindow
  10
  11     An MDI client window is a child of wxMDIParentFrame, and manages zero or
  12     more wxMDIChildFrame objects.
  13
  14     @remarks
  15
  16     The client window is the area where MDI child windows exist. It doesn't have to
  17     cover the whole parent frame; other windows such as toolbars and a help window
  18     might coexist with it. There can be scrollbars on a client window, which are
  19     controlled by the parent window style.
  20
  21     The wxMDIClientWindow class is usually adequate without further derivation, and
  22     it is created automatically when the MDI parent frame is created. If the application
  23     needs to derive a new class, the function wxMDIParentFrame::OnCreateClient() must
  24     be overridden in order to give an opportunity to use a different class of client
  25     window.
  26
  27     Under wxMSW, the client window will automatically have a sunken border style
  28     when the active child is not maximized, and no border style when a child is maximized.
  29
  30     @library{wxcore}
  31     @category{managedwnd}
  32
  33     @see wxMDIChildFrame, wxMDIParentFrame, wxFrame
  34 */
  35 class wxMDIClientWindow : public wxWindow
  36 {
  37 public:
  38     /**
  39         Default constructor.
  40
  41         Objects of this class are only created by wxMDIParentFrame which uses
  42         the default constructor and calls CreateClient() immediately
  43         afterwards.
  44      */
  45     wxMDIClientWindow();
  46
  47     /**
  48         Called by wxMDIParentFrame immediately after creating the client
  49         window.
  50
  51         This function may be overridden in the derived class but the base class
  52         version must usually be called first to really create the window.
  53
  54         @param parent
  55             The window parent.
  56         @param style
  57             The window style. Only wxHSCROLL and wxVSCROLL bits are meaningful
  58             here.
  59
  60     */
  61     virtual bool CreateClient(wxMDIParentFrame* parent, long style = 0);
  62 };
  63
  64
  65
  66 /**
  67     @class wxMDIParentFrame
  68
  69     An MDI (Multiple Document Interface) parent frame is a window which can
  70     contain MDI child frames in its client area which emulates the full
  71     desktop.
  72
  73     MDI is a user-interface model in which all the window reside inside the
  74     single parent window as opposed to being separate from each other. It
  75     remains popular despite dire warnings from Microsoft itself (which
  76     popularized this model in the first model) that MDI is obsolete.
  77
  78     An MDI parent frame always has a wxMDIClientWindow associated with it,
  79     which is the parent for MDI child frames. In the simplest case, the client
  80     window takes up the entire parent frame area but it is also possible to
  81     resize it to be smaller in order to have other windows in the frame, a
  82     typical example is using a sidebar along one of the window edges.
  83
  84     The appearance of MDI applications differs between different ports. The
  85     classic MDI model, with child windows which can be independently moved,
  86     resized etc, is only available under MSW, which provides native support for
  87     it. In Mac ports, multiple top level windows are used for the MDI children
  88     too and the MDI parent frame itself is invisible, to accommodate the native
  89     look and feel requirements. In all the other ports, a tab-based MDI
  90     implementation (sometimes called TDI) is used and so at most one MDI child
  91     is visible at any moment (child frames are always maximized).
  92
  93     @remarks
  94
  95     Although it is possible to have multiple MDI parent frames, a typical MDI
  96     application has a single MDI parent frame window inside which multiple MDI
  97     child frames, i.e. objects of class wxMDIChildFrame, can be created.
  98
  99
 100     @beginStyleTable
 101
 102     There are no special styles for this class, all wxFrame styles apply to it
 103     in the usual way. The only exception is that wxHSCROLL and wxVSCROLL styles
 104     apply not to the frame itself but to the client window, so that using them
 105     enables horizontal and vertical scrollbars for this window and not the
 106     frame.
 107
 108     @endStyleTable
 109
 110     @library{wxcore}
 111     @category{managedwnd}
 112
 113     @see wxMDIChildFrame, wxMDIClientWindow, wxFrame, wxDialog
 114 */
 115 class wxMDIParentFrame : public wxFrame
 116 {
 117 public:
 118
 119     /**
 120         Default constructor.
 121
 122         Use Create() for the objects created using this constructor.
 123     */
 124     wxMDIParentFrame();
 125
 126     /**
 127         Constructor, creating the window.
 128
 129         Notice that if you override virtual OnCreateClient() method you
 130         shouldn't be using this constructor but the default constructor and
 131         Create() as otherwise your overridden method is never going to be
 132         called because of the usual C++ virtual call resolution rules.
 133
 134         @param parent
 135             The window parent. Usually is @NULL.
 136         @param id
 137             The window identifier. It may take a value of @c wxID_ANY to
 138             indicate a default value.
 139         @param title
 140             The caption to be displayed on the frame's title bar.
 141         @param pos
 142             The window position. The value ::wxDefaultPosition indicates a
 143             default position, chosen by either the windowing system or
 144             wxWidgets, depending on platform.
 145         @param size
 146             The window size. The value ::wxDefaultSize indicates a default
 147             size, chosen by either the windowing system or wxWidgets, depending
 148             on platform.
 149         @param style
 150             The window style. Default value includes wxHSCROLL and wxVSCROLL
 151             styles.
 152         @param name
 153             The name of the window. This parameter is used to associate a name
 154             with the item, allowing the application user to set Motif resource
 155             values for individual windows.
 156
 157         @remarks
 158
 159         Under wxMSW, the client window will automatically have a sunken
 160         border style when the active child is not maximized, and no border
 161         style when a child is maximized.
 162
 163         @see Create(), OnCreateClient()
 164     */
 165     wxMDIParentFrame(wxWindow* parent, wxWindowID id,
 166                      const wxString& title,
 167                      const wxPoint& pos = wxDefaultPosition,
 168                      const wxSize& size = wxDefaultSize,
 169                      long style = wxDEFAULT_FRAME_STYLE | wxVSCROLL | wxHSCROLL,
 170                      const wxString& name = wxFrameNameStr);
 171
 172     /**
 173         Destructor.
 174
 175         Destroys all child windows and menu bar if present.
 176     */
 177     virtual ~wxMDIParentFrame();
 178
 179     /**
 180         Activates the MDI child following the currently active one.
 181
 182         The MDI children are maintained in an ordered list and this function
 183         switches to the next element in this list, wrapping around the end of
 184         it if the currently active child is the last one.
 185
 186         @see ActivatePrevious()
 187     */
 188     virtual void ActivateNext();
 189
 190     /**
 191         Activates the MDI child preceding the currently active one.
 192
 193         @see ActivateNext()
 194     */
 195     virtual void ActivatePrevious();
 196
 197     /**
 198         Arranges any iconized (minimized) MDI child windows.
 199
 200         This method is only implemented in MSW MDI implementation and does
 201         nothing under the other platforms.
 202
 203         @see Cascade(), Tile()
 204     */
 205     virtual void ArrangeIcons();
 206
 207     /**
 208         Arranges the MDI child windows in a cascade.
 209
 210         This method is only implemented in MSW MDI implementation and does
 211         nothing under the other platforms.
 212
 213         @see Tile(), ArrangeIcons()
 214     */
 215     virtual void Cascade();
 216
 217     /**
 218         Used in two-step frame construction.
 219
 220         See wxMDIParentFrame() for further details.
 221     */
 222     bool Create(wxWindow* parent,
 223                 wxWindowID id,
 224                 const wxString& title,
 225                 const wxPoint& pos = wxDefaultPosition,
 226                 const wxSize& size = wxDefaultSize,
 227                 long style = wxDEFAULT_FRAME_STYLE | wxVSCROLL | wxHSCROLL,
 228                 const wxString& name = wxFrameNameStr);
 229
 230     /**
 231         Returns a pointer to the active MDI child, if there is one.
 232
 233         If there are any children at all this function returns a non-@NULL
 234         pointer.
 235     */
 236     virtual wxMDIChildFrame* GetActiveChild() const;
 237
 238     /**
 239         Returns a pointer to the client window.
 240
 241         @see OnCreateClient()
 242     */
 243     wxMDIClientWindowBase* GetClientWindow() const;
 244
 245     /**
 246         Returns the current MDI Window menu.
 247
 248         Unless wxFRAME_NO_WINDOW_MENU style was used, a default menu listing
 249         all the currently active children and providing the usual operations
 250         (tile, cascade, ...) on them is created automatically by the library
 251         and this function can be used to retrieve it. Notice that the default
 252         menu can be replaced by calling SetWindowMenu().
 253
 254         This function is currently not available under OS X.
 255
 256         @return The current Window menu or @NULL.
 257     */
 258     wxMenu *GetWindowMenu() const;
 259
 260     /**
 261         Returns whether the MDI implementation is tab-based.
 262
 263         Currently only the MSW port uses the real MDI. In Mac ports the usual
 264         SDI is used, as common under this platforms, and all the other ports
 265         use TDI implementation.
 266
 267         TDI-based MDI applications have different appearance and functionality
 268         (e.g. child frames can't be minimized and only one of them is visible
 269         at any given time) so the application may need to adapt its interface
 270         somewhat depending on the return value of this function.
 271      */
 272     static bool IsTDI();
 273
 274     /**
 275         Override this to return a different kind of client window.
 276
 277         If you override this function, you must create your parent frame in two
 278         stages, or your function will never be called, due to the way C++
 279         treats virtual functions called from constructors. For example:
 280
 281         @code
 282         frame = new MyParentFrame;
 283         frame->Create(parent, myParentFrameId, "My Parent Frame");
 284         @endcode
 285
 286         @remarks
 287
 288         You might wish to derive from wxMDIClientWindow in order to implement
 289         different erase behaviour, for example, such as painting a bitmap on
 290         the background.
 291
 292         Note that it is probably impossible to have a client window that scrolls
 293         as well as painting a bitmap or pattern, since in @b OnScroll, the scrollbar
 294         positions always return zero.
 295
 296         @see GetClientWindow(), wxMDIClientWindow
 297     */
 298     virtual wxMDIClientWindow* OnCreateClient();
 299
 300     /**
 301         Replace the current MDI Window menu.
 302
 303         Ownership of the menu object passes to the frame when you call this
 304         function, i.e. the menu will be deleted by it when it's no longer
 305         needed (usually when the frame itself is deleted or when
 306         SetWindowMenu() is called again).
 307
 308         To remove the window completely, you can use the wxFRAME_NO_WINDOW_MENU
 309         window style but this function also allows to do it by passing @NULL
 310         pointer as @a menu.
 311
 312         The menu may include the items with the following standard identifiers
 313         (but may use arbitrary text and help strings and bitmaps for them):
 314             - @c wxID_MDI_WINDOW_CASCADE
 315             - @c wxID_MDI_WINDOW_TILE_HORZ
 316             - @c wxID_MDI_WINDOW_TILE_VERT
 317             - @c wxID_MDI_WINDOW_ARRANGE_ICONS
 318             - @c wxID_MDI_WINDOW_PREV
 319             - @c wxID_MDI_WINDOW_NEXT
 320         All of which are handled by wxMDIParentFrame itself. If any other
 321         commands are used in the menu, the derived frame should handle them.
 322
 323         This function is currently not available under OS X.
 324
 325         @param menu
 326             The menu to be used instead of the standard MDI Window menu or @NULL.
 327     */
 328     virtual void SetWindowMenu(wxMenu* menu);
 329
 330     /**
 331         Tiles the MDI child windows either horizontally or vertically depending
 332         on whether @a orient is @c wxHORIZONTAL or @c wxVERTICAL.
 333
 334         This method is only implemented in MSW MDI implementation and does
 335         nothing under the other platforms.
 336
 337     */
 338     virtual void Tile(wxOrientation orient = wxHORIZONTAL);
 339 };
 340
 341
 342
 343 /**
 344     @class wxMDIChildFrame
 345
 346     An MDI child frame is a frame that can only exist inside a
 347     wxMDIClientWindow, which is itself a child of wxMDIParentFrame.
 348
 349     @beginStyleTable
 350     All of the standard wxFrame styles can be used but most of them are ignored
 351     by TDI-based MDI implementations.
 352     @endStyleTable
 353
 354     @remarks
 355     Although internally an MDI child frame is a child of the MDI client window,
 356     in wxWidgets you create it as a child of wxMDIParentFrame. In fact, you can
 357     usually forget that the client window exists. MDI child frames are clipped
 358     to the area of the MDI client window, and may be iconized on the client
 359     window. You can associate a menubar with a child frame as usual, although
 360     an MDI child doesn't display its menubar under its own title bar. The MDI
 361     parent frame's menubar will be changed to reflect the currently active
 362     child frame. If there are currently no children, the parent frame's own
 363     menubar will be displayed.
 364
 365     @library{wxcore}
 366     @category{managedwnd}
 367
 368     @see wxMDIClientWindow, wxMDIParentFrame, wxFrame
 369 */
 370 class wxMDIChildFrame : public wxFrame
 371 {
 372 public:
 373     /**
 374         Default constructor.
 375     */
 376     wxMDIChildFrame();
 377
 378     /**
 379         Constructor, creating the window.
 380
 381         @param parent
 382             The window parent. This should not be @NULL.
 383         @param id
 384             The window identifier. It may take a value of -1 to indicate a default
 385             value.
 386         @param title
 387             The caption to be displayed on the frame's title bar.
 388         @param pos
 389             The window position. The value ::wxDefaultPosition indicates a default position,
 390             chosen by either the windowing system or wxWidgets, depending on platform.
 391         @param size
 392             The window size. The value ::wxDefaultSize indicates a default size, chosen by
 393             either the windowing system or wxWidgets, depending on platform.
 394         @param style
 395             The window style. See wxMDIChildFrame.
 396         @param name
 397             The name of the window. This parameter is used to associate a name with the
 398             item, allowing the application user to set Motif resource values for individual
 399             windows.
 400
 401         @see Create()
 402     */
 403     wxMDIChildFrame(wxMDIParentFrame* parent, wxWindowID id,
 404                     const wxString& title,
 405                     const wxPoint& pos = wxDefaultPosition,
 406                     const wxSize& size = wxDefaultSize,
 407                     long style = wxDEFAULT_FRAME_STYLE,
 408                     const wxString& name = wxFrameNameStr);
 409
 410     /**
 411         Destructor. Destroys all child windows and menu bar if present.
 412     */
 413     virtual ~wxMDIChildFrame();
 414
 415     /**
 416         Activates this MDI child frame.
 417
 418         @see Maximize(), Restore()
 419     */
 420     virtual void Activate();
 421
 422     /**
 423         Used in two-step frame construction.
 424         See wxMDIChildFrame() for further details.
 425     */
 426     bool Create(wxMDIParentFrame* parent, wxWindowID id, const wxString& title,
 427                 const wxPoint& pos = wxDefaultPosition,
 428                 const wxSize& size = wxDefaultSize,
 429                 long style = wxDEFAULT_FRAME_STYLE,
 430                 const wxString& name = wxFrameNameStr);
 431
 432     /**
 433         Returns the MDI parent frame containing this child.
 434
 435         Notice that this may return a different object than GetParent() as the
 436         child frames may be created as children of the client window
 437         internally.
 438      */
 439     wxMDIParentFrame *GetMDIParent() const;
 440
 441     /**
 442         Returns true for MDI children in TDI implementations.
 443
 444         TDI-based implementations represent MDI children as pages in a
 445         wxNotebook and so they are always maximized and can't be restored or
 446         iconized.
 447
 448         @see wxMDIParentFrame::IsTDI().
 449      */
 450     virtual bool IsAlwaysMaximized() const;
 451
 452     /**
 453         Maximizes this MDI child frame.
 454
 455         This function doesn't do anything if IsAlwaysMaximized() returns @true.
 456
 457         @see Activate(), Restore()
 458     */
 459     virtual void Maximize(bool maximize = true);
 460
 461     /**
 462         Restores this MDI child frame (unmaximizes).
 463
 464         This function doesn't do anything if IsAlwaysMaximized() returns @true.
 465
 466         @see Activate(), Maximize()
 467     */
 468     virtual void Restore();
 469 };
 470