Using TDockableControlBar

Date: 8 February 1997
Author: Christopher Kohlhoff

Overview

This article looks at how to use TDockableControlBar. TDockableControlBar is a class that provides a toolbar style window (like the Windows 95 common control), however TDockableControlBar can also be used in 16-bit applications. You can download the example project from here. Note that the easiest way to add a control bar is to generate an AppExpert application.

Before You Start

Before adding the code to add a control bar, there are some things that have to be added:

The frame window to which you are going to add the control bar (usually the application main window) must be derived from either TDecoratedFrame (for SDI or Dialog Client applications) or from TDecoratedMDIFrame (for MDI applications).
For each button that you want to place on the control bar, create a small bitmap resouce to go on its face. The system button face colour (light grey) will be automatically mapped to the end user's button face colour.

Creating the Control Bar

Creating a control bar involves the following:

Create a THarbor for the control bar if you do not already have one. The THarbor class takes care of the docking procedure (sounds a bit like the space shuttle!).
// frame is a pointer to the decorated frame Harbor = new THarbor(*frame);
Create the control bar itself:
Toolbar = new TMyToolbar(frame);
Add the buttons and other gadgets to the control bar:
// insert a button gadget Toolbar->Insert(*new TButtonGadget(CM_FILESAVE, // the bitmap CM_FILESAVE));// the command // insert a separator Toolbar->Insert(*new TSeparatorGadget(6));
Workaround a problem with the class to make it initially horizontal when not docked:
TRect rect = Toolbar->GetWindowRect(); TSize size(rect.Width(), rect.Height()); Toolbar->Layout(alTop, &size);
Add the control bar to the harbor:
Harbor->Insert(*Toolbar, alTop);

Showing and Hiding the Control Bar

This following example shows how to allow your control bar to be shown or hidden by the user. When shown, it is at the position that it was last visible.

Make your control bar from the following class derived from TDockableControlBar (instead of TDockableControlBar itself):

class TMyToolbar : public TDockableControlBar { public: TMyToolbar(TWindow* parent) : TDockableControlBar(parent) {} void Hide() { GetHarbor()->Remove(*this); } void Show(THarbor* harbor) { harbor->Insert(*this, Location, &Rect.TopLeft()); harbor->Move(*this, Location, &Rect.TopLeft()); } void SavePosition() { // get the absolute location of the toolbar // TDockingSlip* dockingSlip = TYPESAFE_DOWNCAST(Parent, TDockingSlip); Location = (dockingSlip ? dockingSlip->GetLocation() : alTop); // get the rectangle of the toolbar // TFloatingSlip* floatingSlip = TYPESAFE_DOWNCAST(Parent, TFloatingSlip); if (floatingSlip) floatingSlip->GetWindowRect(Rect); else GetRect(Rect); } TResult WindowProc(uint msg, TParam1 p1, TParam2 p2) { if (msg == WM_SHOWWINDOW && !p1) // we are being hidden SavePosition(); return TDockableControlBar::WindowProc(msg, p1, p2); } protected: TRect Rect; TAbsLocation Location; };
Add menu items and handlers to allow the user to toggle visibility:

DEFINE_RESPONSE_TABLE1(TDCBApp, TApplication) // ... EV_COMMAND(CM_VIEWTOOLBAR, CmViewToolbar), EV_COMMAND_ENABLE(CM_VIEWTOOLBAR, CeViewToolbar), // ... END_RESPONSE_TABLE; void TDCBApp::CmViewToolbar() { if (Toolbar->IsWindowVisible()) Toolbar->Hide(); else Toolbar->Show(Harbor); } void TDCBApp::CeViewToolbar(TCommandEnabler &tce) { tce.SetCheck(Toolbar->IsWindowVisible()); }