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