interface/mdi.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        mdi.h
   3 // Purpose:     documentation for wxMDIClientWindow class
   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{FIXME}
  18
  19     @seealso
  20     wxMDIChildFrame, wxMDIParentFrame, wxFrame
  21 */
  22 class wxMDIClientWindow : public wxWindow
  23 {
  24 public:
  25     //@{
  26     /**
  27         Constructor, creating the window.
  28
  29         @param parent
  30             The window parent.
  31         @param style
  32             The window style. Currently unused.
  33
  34         @remarks The second style of constructor is called within
  35                  wxMDIParentFrame::OnCreateClient.
  36
  37         @see wxMDIParentFrame::wxMDIParentFrame, wxMDIParentFrame::OnCreateClient
  38     */
  39     wxMDIClientWindow();
  40     wxMDIClientWindow(wxMDIParentFrame* parent, long style = 0);
  41     //@}
  42
  43     /**
  44         Destructor.
  45     */
  46     ~wxMDIClientWindow();
  47
  48     /**
  49         Used in two-step frame construction. See wxMDIClientWindow()
  50         for further details.
  51     */
  52     bool CreateClient(wxMDIParentFrame* parent, long style = 0);
  53 };
  54
  55
  56 /**
  57     @class wxMDIParentFrame
  58     @wxheader{mdi.h}
  59
  60     An MDI (Multiple Document Interface) parent frame is a window which can contain
  61     MDI child frames in its own 'desktop'. It is a convenient way to avoid window
  62     clutter,
  63     and is used in many popular Windows applications, such as Microsoft Word(TM).
  64
  65     @beginStyleTable
  66     @style{wxCAPTION}:
  67            Puts a caption on the frame.
  68     @style{wxDEFAULT_FRAME_STYLE}:
  69            Defined as wxMINIMIZE_BOX |  wxMAXIMIZE_BOX |  wxTHICK_FRAME |
  70            wxSYSTEM_MENU |  wxCAPTION.
  71     @style{wxHSCROLL}:
  72            Displays a horizontal scrollbar in the client window, allowing the
  73            user to view child frames that are off the current view.
  74     @style{wxICONIZE}:
  75            Display the frame iconized (minimized) (Windows only).
  76     @style{wxMAXIMIZE}:
  77            Displays the frame maximized (Windows only).
  78     @style{wxMAXIMIZE_BOX}:
  79            Displays a maximize box on the frame (Windows and Motif only).
  80     @style{wxMINIMIZE}:
  81            Identical to wxICONIZE.
  82     @style{wxMINIMIZE_BOX}:
  83            Displays a minimize box on the frame (Windows and Motif only).
  84     @style{wxRESIZE_BORDER}:
  85            Displays a resizeable border around the window (Motif only; for
  86            Windows, it is implicit in wxTHICK_FRAME).
  87     @style{wxSTAY_ON_TOP}:
  88            Stay on top of other windows (Windows only).
  89     @style{wxSYSTEM_MENU}:
  90            Displays a system menu (Windows and Motif only).
  91     @style{wxTHICK_FRAME}:
  92            Displays a thick frame around the window (Windows and Motif only).
  93     @style{wxVSCROLL}:
  94            Displays a vertical scrollbar in the client window, allowing the
  95            user to view child frames that are off the current view.
  96     @style{wxFRAME_NO_WINDOW_MENU}:
  97            Under Windows, removes the Window menu that is normally added
  98            automatically.
  99     @endStyleTable
 100
 101     @library{wxcore}
 102     @category{managedwnd}
 103
 104     @seealso
 105     wxMDIChildFrame, wxMDIClientWindow, wxFrame, wxDialog
 106 */
 107 class wxMDIParentFrame : public wxFrame
 108 {
 109 public:
 110     //@{
 111     /**
 112         Constructor, creating the window.
 113
 114         @param parent
 115             The window parent. This should be @NULL.
 116         @param id
 117             The window identifier. It may take a value of -1 to indicate a default
 118         value.
 119         @param title
 120             The caption to be displayed on the frame's title bar.
 121         @param pos
 122             The window position. The value wxDefaultPosition indicates a default position,
 123         chosen by
 124             either the windowing system or wxWidgets, depending on platform.
 125         @param size
 126             The window size. The value wxDefaultSize indicates a default size, chosen by
 127             either the windowing system or wxWidgets, depending on platform.
 128         @param style
 129             The window style. See wxMDIParentFrame.
 130         @param name
 131             The name of the window. This parameter is used to associate a name with the
 132         item,
 133             allowing the application user to set Motif resource values for
 134             individual windows.
 135
 136         @remarks During the construction of the frame, the client window will be
 137                  created. To use a different class from
 138                  wxMDIClientWindow, override
 139                  OnCreateClient().
 140
 141         @see Create(), OnCreateClient()
 142     */
 143     wxMDIParentFrame();
 144     wxMDIParentFrame(wxWindow* parent, wxWindowID id,
 145                      const wxString& title,
 146                      const wxPoint& pos = wxDefaultPosition,
 147                      const wxSize& size = wxDefaultSize,
 148                      long style = wxDEFAULT_FRAME_STYLE | wxVSCROLL | wxHSCROLL,
 149                      const wxString& name = "frame");
 150     //@}
 151
 152     /**
 153         Destructor. Destroys all child windows and menu bar if present.
 154     */
 155     ~wxMDIParentFrame();
 156
 157     /**
 158         Activates the MDI child following the currently active one.
 159
 160         @see ActivatePrevious()
 161     */
 162     void ActivateNext();
 163
 164     /**
 165         Activates the MDI child preceding the currently active one.
 166
 167         @see ActivateNext()
 168     */
 169     void ActivatePrevious();
 170
 171     /**
 172         Arranges any iconized (minimized) MDI child windows.
 173
 174         @see Cascade(), Tile()
 175     */
 176     void ArrangeIcons();
 177
 178     /**
 179         Arranges the MDI child windows in a cascade.
 180
 181         @see Tile(), ArrangeIcons()
 182     */
 183     void Cascade();
 184
 185     /**
 186         Used in two-step frame construction. See wxMDIParentFrame()
 187         for further details.
 188     */
 189     bool Create(wxWindow* parent, wxWindowID id,
 190                 const wxString& title,
 191                 const wxPoint& pos = wxDefaultPosition,
 192                 const wxSize& size = wxDefaultSize,
 193                 long style = wxDEFAULT_FRAME_STYLE | wxVSCROLL | wxHSCROLL,
 194                 const wxString& name = "frame");
 195
 196     /**
 197         Returns a pointer to the active MDI child, if there is one.
 198     */
 199     wxMDIChildFrame* GetActiveChild() const;
 200
 201     /**
 202         This gets the size of the frame 'client area' in pixels.
 203
 204         @param width
 205             Receives the client width in pixels.
 206         @param height
 207             Receives the client height in pixels.
 208
 209         @remarks The client area is the area which may be drawn on by the
 210                  programmer, excluding title bar, border, status bar,
 211                  and toolbar if present.
 212
 213         @see GetToolBar(), SetToolBar(),
 214              wxMDIClientWindow
 215     */
 216     virtual void GetClientSize(int* width, int* height) const;
 217
 218     /**
 219         Returns a pointer to the client window.
 220
 221         @see OnCreateClient()
 222     */
 223     wxMDIClientWindow* GetClientWindow() const;
 224
 225     /**
 226         Returns the window being used as the toolbar for this frame.
 227
 228         @see SetToolBar()
 229     */
 230     virtual wxWindow* GetToolBar() const;
 231
 232     /**
 233         Returns the current Window menu (added by wxWidgets to the menubar). This
 234         function
 235         is available under Windows only.
 236     */
 237     wxMenu* GetWindowMenu() const;
 238
 239     /**
 240         Override this to return a different kind of client window. If you override this
 241         function,
 242         you must create your parent frame in two stages, or your function will never be
 243         called,
 244         due to the way C++ treats virtual functions called from constructors. For
 245         example:
 246
 247         @remarks You might wish to derive from wxMDIClientWindow in order to
 248                  implement different erase behaviour, for example, such
 249                  as painting a bitmap on the background.
 250
 251         @see GetClientWindow(), wxMDIClientWindow
 252     */
 253     virtual wxMDIClientWindow* OnCreateClient();
 254
 255     /**
 256         Sets the window to be used as a toolbar for this
 257         MDI parent window. It saves the application having to manage the positioning
 258         of the toolbar MDI client window.
 259
 260         @param toolbar
 261             Toolbar to manage.
 262
 263         @remarks When the frame is resized, the toolbar is resized to be the
 264                  width of the frame client area, and the toolbar height
 265                  is kept the same.
 266
 267         @see GetToolBar(), GetClientSize()
 268     */
 269     virtual void SetToolBar(wxWindow* toolbar);
 270
 271     /**
 272         Call this to change the current Window menu. Ownership of the menu object
 273         passes to
 274         the frame when you call this function.
 275         This call is available under Windows only.
 276         To remove the window completely, use the wxFRAME_NO_WINDOW_MENU window style.
 277     */
 278     void SetWindowMenu(wxMenu* menu);
 279
 280     /**
 281         Tiles the MDI child windows either horizontally or vertically depending on
 282         whether @a orient is wxHORIZONTAL or wxVERTICAL.
 283         Currently only implemented for MSW, does nothing under the other platforms.
 284     */
 285     void Tile(wxOrientation orient = wxHORIZONTAL);
 286 };
 287
 288
 289 /**
 290     @class wxMDIChildFrame
 291     @wxheader{mdi.h}
 292
 293     An MDI child frame is a frame that can only exist on a wxMDIClientWindow,
 294     which is itself a child of wxMDIParentFrame.
 295
 296     @beginStyleTable
 297     @style{wxCAPTION}:
 298            Puts a caption on the frame.
 299     @style{wxDEFAULT_FRAME_STYLE}:
 300            Defined as wxMINIMIZE_BOX |  wxMAXIMIZE_BOX |  wxTHICK_FRAME |
 301            wxSYSTEM_MENU |  wxCAPTION.
 302     @style{wxICONIZE}:
 303            Display the frame iconized (minimized) (Windows only).
 304     @style{wxMAXIMIZE}:
 305            Displays the frame maximized (Windows only).
 306     @style{wxMAXIMIZE_BOX}:
 307            Displays a maximize box on the frame (Windows and Motif only).
 308     @style{wxMINIMIZE}:
 309            Identical to wxICONIZE.
 310     @style{wxMINIMIZE_BOX}:
 311            Displays a minimize box on the frame (Windows and Motif only).
 312     @style{wxRESIZE_BORDER}:
 313            Displays a resizeable border around the window (Motif only; for
 314            Windows, it is implicit in wxTHICK_FRAME).
 315     @style{wxSTAY_ON_TOP}:
 316            Stay on top of other windows (Windows only).
 317     @style{wxSYSTEM_MENU}:
 318            Displays a system menu (Windows and Motif only).
 319     @style{wxTHICK_FRAME}:
 320            Displays a thick frame around the window (Windows and Motif only).
 321     @endStyleTable
 322
 323     @library{wxcore}
 324     @category{managedwnd}
 325
 326     @seealso
 327     wxMDIClientWindow, wxMDIParentFrame, wxFrame
 328 */
 329 class wxMDIChildFrame : public wxFrame
 330 {
 331 public:
 332     //@{
 333     /**
 334         Constructor, creating the window.
 335
 336         @param parent
 337             The window parent. This should not be @NULL.
 338         @param id
 339             The window identifier. It may take a value of -1 to indicate a default
 340         value.
 341         @param title
 342             The caption to be displayed on the frame's title bar.
 343         @param pos
 344             The window position. The value wxDefaultPosition indicates a default position,
 345         chosen by
 346             either the windowing system or wxWidgets, depending on platform.
 347         @param size
 348             The window size. The value wxDefaultSize indicates a default size, chosen by
 349             either the windowing system or wxWidgets, depending on platform.
 350         @param style
 351             The window style. See wxMDIChildFrame.
 352         @param name
 353             The name of the window. This parameter is used to associate a name with the
 354         item,
 355             allowing the application user to set Motif resource values for
 356             individual windows.
 357
 358         @remarks None.
 359
 360         @see Create()
 361     */
 362     wxMDIChildFrame();
 363     wxMDIChildFrame(wxMDIParentFrame* parent, wxWindowID id,
 364                     const wxString& title,
 365                     const wxPoint& pos = wxDefaultPosition,
 366                     const wxSize& size = wxDefaultSize,
 367                     long style = wxDEFAULT_FRAME_STYLE,
 368                     const wxString& name = "frame");
 369     //@}
 370
 371     /**
 372         Destructor. Destroys all child windows and menu bar if present.
 373     */
 374     ~wxMDIChildFrame();
 375
 376     /**
 377         Activates this MDI child frame.
 378
 379         @see Maximize(), Restore()
 380     */
 381     void Activate();
 382
 383     /**
 384         Used in two-step frame construction. See wxMDIChildFrame()
 385         for further details.
 386     */
 387     bool Create(wxWindow* parent, wxWindowID id,
 388                 const wxString& title,
 389                 const wxPoint& pos = wxDefaultPosition,
 390                 const wxSize& size = wxDefaultSize,
 391                 long style = wxDEFAULT_FRAME_STYLE,
 392                 const wxString& name = "frame");
 393
 394     /**
 395         Maximizes this MDI child frame.
 396
 397         @see Activate(), Restore()
 398     */
 399     void Maximize(bool maximize);
 400
 401     /**
 402         Restores this MDI child frame (unmaximizes).
 403     */
 404     void Restore();
 405 };