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