wxDockIt

From WxWiki
Jump to: navigation, search

wxDockIt can be found here. A more advanced (but also more complicated) docking library is WxIFM, another advanced frame/toolbar library is WxAUI and a (reportedly) more buggy implementation in contrib is WxFrameLayout.

wxDockIt works with wxGTK. Version 2.1 (released July 23, 2005) contains GNU configure script and is wxunicode compliant.

On July 7, 2006, Mark McCormack - the author of wxDockIt - announced the end of wxDockIt.

Using wxDockIt

Using wxDockIt is pretty easy but there is pretty much no offical documentation. There are a couple of samples to learn from (although, they are both very similar; one using a MDI interface and another, nearly identical, using SDI interface).

From my understanding and use of it all, you must have a wxLayoutManager. You use this to create dock hosts which are where you can attach wxDockWindows. A wxDockWindow contains a client window which is essentially, what is inside the window.

So, here's a small example adapted from the examples. This would be placed wherever you make a frames child controls (Create() for instance):

  // First, lets create dockable window (while set this one to initially dock to the bottom)
  
  wxDockWindow *dock_window1 = new wxDockWindow(this,               // Parent window
                                                wxID_ANY,           // Id
                                                "Dock Window 1",    // Text to be used in the
                                                                    // drag/caption portion of the
                                                                    // dock.
                                                wxPoint(64, 64),    // Position when it is not docked.
                                                wxSize(128, 128));  // Size when it is not docked.
  
  
  // Now create and add a text control to this dock window 
  
  wxTextCtrl *dock_txt = new wxTextCtrl(this,                       // Parent (it will Reparent to the
                                                                    // wxDockWindow when it is placed
                                                                    // in it).
                                        wxID_ANY,                   // Id
                                        "Text",                     // Initial text
                                        wxDefaultPosition,          // Position
                                        wxDefaultSize,              // Size
                                        wxTE_MULTILINE);            // Style
  
  dock_window1->SetClient(dock_txt); // Places the text control inside the wxDockWindow
  
  
  // Create another dock window
  
  wxDockWindow *dock_window2 = new wxDockWindow(this,               // Parent window
                                                wxID_ANY,           // Id
  
  
  
                                                "Dock Window 2",    // Text to be used in the
                                                                    // drag/caption portion of the
                                                                    // dock.
                                                wxPoint(64, 64),    // Position when it is not docked.
                                                wxSize(128, 128));  // Size when it is not docked.
  
  
  // Retreive the current client window and change the background color to a light blue
  
  dock_window2->GetClient()->SetBackgroundColour(wxColour(0, 128, 255));
  
  
  wxLayoutManager* layout_manager = new wxLayoutManager( this ); // The parameter is the frame to
                                                                 // attach this wxLayoutManager to.
  
  layout_manager->AddDefaultHosts();           // Creates the Top, Right, Bottom, and Left dock hosts.
  
  
  // You must call AddDockWindow for each wxDockWindow you want this wxLayoutManager to recognize and handle (this does not dock any of the windows though).
  
  layout_manager->AddDockWindow(dock_window1);
  layout_manager->AddDockWindow(dock_window2);
  
  
  
  
  // Now lets dock the first window to the bottom. Retrieve the HostInfo first, then use it to tell the layout manager where to dock.
  
  HostInfo bottom_hi = layout_manager->GetDockHost(wxDEFAULT_BOTTOM_HOST);
  layout_manager->DockWindow(dock_window1, bottom_hi);
  
  
  
  // Since we already have the bottom host area's info, lets increase the size of the area a window must enter before it snaps into the dock region.
  
  bottom_hi.pHost->SetAreaSize(128);
  
  
  
  // dock_window2 won't be docked by default but lets go ahead and show it floating off by itself
  
  dock_window2->Show();

Also, the window you are using the wxLayoutManager on MUST handle its own size events otherwise the behavior will be very unusual and will simply not work a lot of the time.

A simple bit of code such as this (with the appropriate SIZE_EVT specified in the frame's event table) will do the trick:

  void MyFrame::OnSize(wxSizeEvent& arg_event)
  {
    // let the docking system override the placement of the client window
    if(!layout_manager)
    {
      arg_event.Skip();
    }
  }

There are many more features than what I've show here as well as two (that I know of) other classes (wxPane, and wxSlider). I'm still trying to figure out exacly what they are for myself so I won't go and try to explain those. Take a look at the wxDockIt samples for further info.