MDIGadget()

Syntax

Result = MDIGadget(#Gadget, x, y, Width, Height, SubMenu, MenuItem [, Flags])

Creates a client area, in which child windows can be displayed. These child windows are fully movable and sizable by the user in this area. If #PB_Any is used as '#Gadget' parameter, the new gadget number will be returned as 'Result'.

An MDIGadget() is always connected to a window Menu (see CreateMenu()). Therefore a MDIGadget() can only be put on a window that has a menu attached to it. The gadget will give the user the opportunity to select the child windows through one of the windows submenus. In the 'SubMenu' parameter, you have to specify the submenu index (created with MenuTitle()) where these items will be attached to (the first submenu has the index 0). The Gadget will add a seperator at the end of this menu, and then add one item for each currently displayed child window.

The gadget will require a set of Menu item identifiers (see the 'MenuID' parameter of MenuItem()) to add these menuitems. In the 'MenuItem' parameter of MDIGadget() you have to specify the lowest number that the gadget can use for that purpose. It will use numbers above that, when new child windows are added, so you need to reserve at least as much numbers as you plan to add items. It is recommended to use a number above all menu identifiers of your program, to make sure there is never a collision.

Additional notes:
Because of the connection with the window menu, there can only be one MDIGadget() on a window, however you can put another one in a second window if you wish. You can only put this gadget directly on a window, you can NOT put it inside a ContainerGadget(), SplitterGadget() or PanelGadget().
As the whole point of this gadget is to dynamically display data, it is recommended to use the #PB_Any feature to populate a child window with gadgets.

When using AddGadgetItem() with this gadget, there is actually a new PB window created. All the commands of the Window library can be used with this new window (except StickyWindow()). Of course the number choosen for the new window may not overlap with another open window, otherwise the other window will be closed. After creating an MDI child window, CreateGadgetList() must be called before any gadgets can be added to it. The MDI Gadget does not return any events. Events concerning the childwindows will be received as normal window events (#PB_Event_SizeWindow, #PB_Event_CloseWindow, ...) instead.

The following values can be used in the 'Flags' parameter:

  #PB_MDI_AutoSize       : The gadget will automatically resize itself to fit the parent window.
                           If you have no other gadgets on the window, this is a helpfull option.
  #PB_MDI_BorderLess     : There will be no border drawn around the client area.
  #PB_MDI_NoScrollBars   : When the user drags a childwindow outside of the displayed area, there will be no scrollbars.

You can add a 'mini help' to this gadget by using GadgetToolTip().

The following commands can be used to manage the gadget contents:

- CountGadgetItems() : Return the number of child windows.
- AddGadgetItem() : Add a new child window to the gadget.
- ClearGadgetItemList() : Close all child windows.
- GetGadgetState() : Get the currently focused child window.
- SetGadgetState() : Set the currently focused window, or arrange the child windows. (see GetGadgetState() for more info.)
- SetGadgetAttribute(): With the following attributes:

  #PB_MDI_Image    : Set a background image. An ImageID value must be passed as value. (see ImageID())
  #PB_MDI_TileImage: Set the tile mode. 0 draws the image just once in the top/left corner, 1 repeats the image to fill the whole area

This gadget supports the SetGadgetColor() and GetGadgetColor commands with the #PB_Gadget_BackColor type to change the background color of the MDI area.

Example:

  #Main = 0
  #MDIChild = 1
  If OpenWindow(#Main, 0, 0, 400, 300, "MDIGadget", #PB_Window_SystemMenu|#PB_Window_ScreenCentered|#PB_Window_SizeGadget|#PB_Window_MaximizeGadget)
    If CreateGadgetList(WindowID(#Main)) And CreateMenu(#Main, WindowID(#Main))
      MenuTitle("Menu index 0")
      MenuTitle("MDI windows menu")
        MenuItem(0, "self created item")
        MenuItem(1, "self created item")
        
      MDIGadget(0, 0, 0, 0, 0, 1, 2, #PB_MDI_AutoSize)
        AddGadgetItem(0, #MDIChild, "child window")
        CreateGadgetList(WindowID(#MDIChild))
          ; add gadgets here...
      UseGadgetList(WindowID(#Main)) ; go back to the main window gadgetlist
    EndIf
    Repeat : Until WaitWindowEvent()=#PB_Event_CloseWindow
  EndIf

Supported OS

Windows, Linux