Getting Started

Important Terminology

There are some key terms that all users of IFM should know.

Managed Window

This is the window (or frame, depending on the terminology used by your gui toolkit) that IFM is providing docking for. While this window can technically be any kind of widget supported by your gui toolkit, you will most likely be managing the main top level window for your application.

Child Widget

A Child Widget is any widget in your application that is being positioned by IFM.

Content Widget

This is a special Child Widget that is always visible and is positioned in the center of the Managed Window. It will take up any space within the Managed Window not taken up by the other Child Widgets. The Content Widget is not dockable, it is supposed to remain in the center of the Managed Window.

Component

A Component is the building block of IFM. They can contain Child Widgets or other Components and are used to construct Layouts. Components that contain Child Widgets are also dockable to different locations in the Layout by the user.

Layout

A Layout describes a positioning of all Components (and therefore Child Widgets) within the interface. For example, in an IDE type application there would be multiple layouts. One for coding (the Design Layout), and one for debugging (the Debug Layout). Each layout can use different Child Widgets and Component positions.

Interface

Interface is the general term used to refer collectively to all Components and Child Widgets within the Managed Window.

Create an InterfaceManager instance

    #include <ifm/ifm.h>
    ifm::InterfaceManager *manager = new ifm::InterfaceManager(managed_window, content_widget);

Define your layout

The purpose of IFM is to position Child Widgets within your Interface. In order for IFM to do so, you must tell it what Child Widgets you want it to position and where you would like them to initially appear. Child Widgets are added by specifying their ID. Pointers are not used because pointers can vary between runs of an application while IDs are always the same. The IDs used should be unique throughout the application.

The widgets identified by these IDs need not exist at the time the layout is created. If you call InterfaceManager::set_layout with a Layout that specifies Child Widgets which do not yet exist, the Panels containing those Child Widgets will simply be hidden until their Child Widgets are created. At that point, the Panel will be shown. This behavior is especially convenient when your Interface is very dynamic. Note that the Child Widget must be created with the Managed Window as its parent in order for IFM to notice that it was created.

Warning:

The functionality described above is broken in wxWidgets 2.6.3 due to a bug which causes wxWindowCreateEvent not to be sent for wxControl derivatives. I have a patch which fixes the issue which you can find here: http://sourceforge.net/tracker/index.php?func=detail&aid=1535693&group_id=9863&atid=309863 . This bug is not present in the 2.8 series of wxWidgets.

ifm::layout::Layout is the main Layout object. Layouts are constructed using Container, Panel and TabbedContainer building blocks. The most basic building block is the Panel. It is used to add your child widgets to the layout. Containers are used to control where the Panels are placed in relation to one another (in rows or columns). TabbedContainers let you place multiple Panels in the same location, but only one will be visible at a time.

The easiest way to add children to the layout is by using Layout::add. This is demonstrated below.

    ifm::layout::Layout layout;
    layout.add(new ifm::layout::Panel(CHILD_ONE, "One"), ifm::LEFT); // Add the widget with id CHILD_ONE to the left side
    layout.add(new ifm::layout::Panel(CHILD_TWO, "Two"), ifm::RIGHT); // Add the widget with id CHILD_TWO to the right side
    manager->set_layout(layout);

To create more complicated layouts, you must create Containers or TabbedContainers and use them to arrange your child widgets. This is demonstrated below.

    // Add CHILD_ONE and CHILD_TWO to the left side in a tabbed container
    TabbedContainer leftContainer;
    leftContainer.add(new Panel(CHILD_ONE, "One"));
    leftContainer.add(new Panel(CHILD_TWO, "Two"));
    layout.add(leftContainer.copy(), ifm::LEFT);

    // Add CHILD_THREE and CHILD_FOUR in a row on the bottom
    Container bottomContainer;
    bottomContainer.add(new Panel(CHILD_THREE, "Three"));
    bottomContainer.add(new Panel(CHILD_FOUR, "Four"));
    layout.add(bottomContainer.copy(), ifm::BOTTOM);

For more information as to how you can customize your layout, including adding icons to be displayed on tabs as well as controlling other behavior, see ifm::layout::Panel.

See also:

ifm::layout

Update the layout

When the size of the Managed Window changes, IFM will automatically update the interface to fill up the new client area of the Managed Window. The client area is the size of the window ignoring any borders or decorations like menus or title bars. If you dont want IFM to automatically update the interface for you, you can use ifm::InterfaceManager::automatic_interface_update to disable it. You can enable it again at any time using the same function. When automatic updates are disabled you can use ifm::InterfaceManager::update_interface to update the interface yourself when the size of the Managed Window changes as shown below.

    // When the size of the Managed Window changes
    manager->update_interface(new_client_size);

Cleaning up

It is important to remember to destroy the current layout before the Managed Window is destroyed. If not, InterfaceManager will destroy all Components in its destructor and those Components will attempt to destroy their native widgets. However, because these native widgets were children of the Managed Window, they have already been destroyed. This will probably cause segfaults. Destroying the layout before the Managed Window is destroyed will avoid this problem because the Components will be destroyed before the Managed Window.

    // When the managed window is closing
    manager->destroy_layout();

Note:

This behavior is not set in stone, IFM may automatically do this in future versions.