Step 3: Adding Docking Bars

Gadgets > The ViewFile Application: Building a Simple File Browser > Step 3: Adding Docking Bars

This step explains how to add docking bars (menu bars and toolbars) to the ViewFile application. For information on docking panes, see Docking Panes and Containers.

This step shows you how to perform the following tasks:

Preparing the Main Window for Docking

Creating the Docking Toolbar

Creating the Docking Menu Bar

Integrating Changes into the Application

Previewing the Application

All the changes made in this step are reflected in the file viewfile.cpp.

Preparing the Main Window for Docking

Docking panes, and hence docking toolbars and menu bars, must be docked to dockable containers. Therefore, the application main window must be modified to allow docking operations.

Modifying the Main Window

IlvDockableContainer, a subclass of IlvPanedContainer, is the base class for handling docking panes. In this step, the main window is defined as an IlvDockableMainWindow object in the member function FileViewerApplication::createMainWindow (see Creating the Main Window). IlvDockableMainWindow is a subclass of IlvDockableContainer that implements a standard layout for applications incorporating docking panes. See the section “Building a Standard Application with Docking Panes” in Docking Panes and Containers.

IlvContainer*

FileViewerApplication::createMainWindow(const IlvRect& rect) const

{

return new IlvDockableMainWindow(getDisplay(),

getName(),

rect,

IlvFalse);

}

It is now possible to add docking panes to the application.

Preparing the Panes Creation

The member function FileViewerApplication::makePanels must be modified to include calls to initPanes, which creates the panes, and updatePanes, which updates the paned container layout. See the section “Modifying the Layout of a Paned Containers” in Panes.

void

FileViewerApplication::makePanels(){

// Initialize the main window.

initMainWindow();

// Initialize the panes.

initPanes();

// Initialize the application.

configureApplication();

// Update the main window layout.

getMainWindow()->updatePanes(IlvTrue);

// Show it.

getMainWindow()->show();

}

The initPanes member function calls initMenuBar, which creates the menu bar and initToolBar, which creates the toolbar.

void

FileViewerApplication::initPanes()

{

// Initialize the menu bar.

initMenuBar();

// Initialize the toolbar.

initToolBar();

}

Creating the Docking Toolbar

The initToolBar member function creates the toolbar:

void

FileViewerApplication::initToolBar()

{

IlvToolBar* toolbar = new IlvToolBar(getDisplay(), IlvPoint(0, 0));

// Item Up One Level.

toolbar->insertBitmap(getBitmap("upBm"));

toolbar->getItem(0)->setCallback(UpOneLevel);

toolbar->getItem(0)->setClientData(this);

toolbar->getItem(0)->setToolTip("Up One Level");

// Encapsulate the toolbar into a graphic pane.

IlvGraphicPane* toolbarPane = new IlvAbstractBarPane("Toolbar", toolbar);

// Add the pane to the application on top of the main workspace.

getMainWindow()->addRelativeDockingPane(toolbarPane,

IlvDockableMainWindow::

GetMainWorkspaceName(),

IlvTop);

}

The toolbar contains only one item, the “Up One Level” item. When selected, this item tries to explore the parent of the selected folder. (The items of the selected folder are displayed in the sheet on the right side of the file browser.) The “Up One Level” item is associated with a tooltip. The toolbar is encapsulated in a special graphic pane of type IlvAbstractBarPane, which is added to the main window, just above the workspace.

For more information, see the sections “Using Tooltips in a Toolbar” in Menus, Menu Bars, and Toolbars and “Using the IlvAbstractBarPane Class” in Docking Panes and Containers.

Note: The client data of the item is set to this, making it possible to retrieve a pointer to the application from its callback function. (Remember that the client data is the second parameter of the callback invoked when the item is activated.)

static void

UpOneLevel(IlvGraphic* g, IlvAny arg)

{

// Retrieve a pointer on the application.

FileViewerApplication* application = (FileViewerApplication*)arg;

// Retrieve a pointer on the main window.

FileViewerWindow* window = (FileViewerWindow*)

application->getMainWindow()->getMainWorkspaceViewPane()->getView();

// Retrieve a pointer on the file viewer.

FileViewer* viewer = FileViewerApplication::GetFileViewer(window);

if (viewer) {

// Find the last selected item of the tree.

IlvTreeGadgetItem* item =

viewer->getTreeGadget()->getLastSelectedItem();

// And select its parent.

if (item && item->getParent() && item->getParent()->getParent())

viewer->getTreeGadget()->selectItem(item->getParent(),

IlvTrue,

IlvTrue);

}

Creating the Docking Menu Bar

The initMenuBar member function creates the menu bar:

void

FileViewerApplication::initMenuBar()

{

// The menu bar is in fact an IlvToolBar.

IlvToolBar* menubar = new IlvToolBar(getDisplay(), IlvPoint(0, 0));

// Add two items

menubar->addLabel("File");

menubar->addLabel("Help");

// Create the pane that will encapsulate the menu bar.

IlvGraphicPane* menubarPane = new ApplicationMenuBarPane("Menu Bar",

menubar);

// Change the mode of the menu bar to make it show items on several

// rows, if needed.

menubar->setConstraintMode(IlvTrue);

// Add the pane to the application on top of the main workspace.

getMainWindow()->addRelativeDockingPane(menubarPane,

IlvDockableMainWindow::

GetMainWorkspaceName(),

IlvTop);

// Now fill the menus with popup menus.

IlvPopupMenu* menu;

// Menu File: New / Separator / Exit.

menu = new IlvPopupMenu(getDisplay());

menu->addLabel("Exit");

menu->getItem(0)->setCallback(ExitApplication);

menu->getItem(0)->setClientData(this);

menubar->getItem(0)->setMenu(menu, IlvFalse);

// Menu Help: About.

menu = new IlvPopupMenu(getDisplay());

menu->addLabel("About");

menubar->getItem(1)->setMenu(menu, IlvFalse);

menu->getItem(0)->setCallback(ShowAboutPanel);

menu->getItem(0)->setClientData(this);

}

The menu bar is created and initialized with two items: File and Help. It is then encapsulated into a pane of the ApplicationMenuBarPane class, a subclass of IlvAbstractBarPane class that changes the label orientation according to the bar orientation.

See the section “Customizing Docking Bars” in Docking Panes and Containers.

The Help item of the menu bar has a submenu that contains the About item. This item is attached to a callback that displays a dialog box showing the application name:

void

FileViewerApplication::showVersion()

{

IlvIInformationDialog dialog(getDisplay(), "VIEWFILE Tutorial");

dialog.moveToMouse();

dialog.showModal();

}

For more information, see Dialogs.

Integrating Changes into the Application

The last step consists of modifying the member function FileViewerApplication::configureApplication to include the view of the file viewer in the main workspace of the application main window. This workspace is represented by a view pane that is created by default and can be retrieved using the getMainWorkspaceViewPane.

See “Using the IlvDockableMainWindow Class” in Docking Panes and Containers.

void

FileViewerApplication::configureApplication()

{

// Create the file viewer window.

FileViewerWindow* window = createFileViewerWindow(getMainWindow(),

IlvRect(0, 0, 400, 200));

// Replace the view of the main workspace pane with the file viewer window.

getMainWindow()->getMainWorkspaceViewPane()->setView(window);

// Create the file viewer using the file viewer window.

FileViewer* viewer = createFileViewer(window);

// Link the file viewer with its window.

// This is used in the UpOneLevel callback.

SetFileViewer(window, viewer);

// Initialize the file viewer.

viewer->init(IlvPathName("/"));

}

The factory member function createFileViewerWindow creates a FileViewerWindow object as a subview of the provided view. The created view is set as the view pane representing the main workspace. Finally, the FileViewer object is created and initialized, using the same method as in the previous step.

Previewing the Application

This is the end of Step 3. Your application window should look like this:

The ViewFile Application After Step 3

Version 6.3