Notes for week 10

For this week's links click here.

Toolbars and ToolBoxes

When you create a program using AppExpert, one of the check box options is for a Toolbar. Toolbars appear at the top, bottom, left or right of a window and allow users to select a menu item by clicking on an icon. The default for the AppExpert tool bar is a horizontal bar at the top of the window. Toolboxes must be created by the programmer, but can appear at the top, bottom, left side or right side. The programmer also controls the number of columns and rows of icons. In additon it is possible to create a floating toolbox that may be dragged around the window.

ToolBars

ToolBar Created by AppExpert

When you use AppExpert to create the toolbar, it creates the function SetupSpeedBar in the TApplication class and calls this function in the InitMainWindow function. This code could also be inserted directly in the constructor for the SDIDecFrame, or the function setupSpeedBar can be moved to the SDIDecFrame as I have done. This function is then called from the constructor for SDIDecFrame. The buttons listed in this toolbar correspond to the default menu items. Each button gadget has the constant CM_******* repeated twice as a parameter. One of these parameters is the command message, while the other is the number associated with the bitmap placed on the button face.

If you want to add more items you have to create new buttons for each menu item you want to include. You can also create commands that are only handled by the tool bar. In this case I created the bitmap CM_MOVEBAR and associated it with the handler cmMoveBar by inserting

 EV_COMMAND(CM_MOVEBAR,cmMoveBar),

into the response table for the SDIDecFrame. This command will shift the bar from top to left and vice versa. See the discussion of this function and creating icons below.

Most of the code initializes the items found in the toolbar. The last line of the function inserts the toolbar in the frame. I have added some of my own commands (see the next section), including the CM_MOVEBAR which has the icon shown below. I wanted to be able to hide and show the tool bar, so I created a menu item corresponding to the identifier CM_TOOL_BAR. This identifier will cause the bar to appear and disappear because I made the following assignment.

cb->Attr.Id=CM_TOOL_BAR;

No handler is necessary for this command. I used barOnTop to indicate which way the bar will be flipped by the handler for CM_MOVEBAR.

void SDIDecFrame::setupSpeedBar()
{
	 //
	 // Create default toolbar New and associate toolbar buttons with commands.
	 //

	 cb = new TControlBar(this);
	 cb->Insert(*new TButtonGadget(CM_FILENEW, CM_FILENEW));
	 cb->Insert(*new TButtonGadget(CM_FILEOPEN, CM_FILEOPEN));
	 cb->Insert(*new TButtonGadget(CM_FILESAVE, CM_FILESAVE));
	 cb->Insert(*new TSeparatorGadget(6));
	 cb->Insert(*new TButtonGadget(CM_EDITCUT, CM_EDITCUT));
	 cb->Insert(*new TButtonGadget(CM_EDITCOPY, CM_EDITCOPY));
	 cb->Insert(*new TButtonGadget(CM_EDITPASTE, CM_EDITPASTE));
	 cb->Insert(*new TSeparatorGadget(6));
	 cb->Insert(*new TButtonGadget(CM_EDITUNDO, CM_EDITUNDO));
	 cb->Insert(*new TSeparatorGadget(6));
	 cb->Insert(*new TButtonGadget(CM_EDITFIND, CM_EDITFIND));
	 cb->Insert(*new TButtonGadget(CM_EDITFINDNEXT, CM_EDITFINDNEXT));
	 cb->Insert(*new TSeparatorGadget(6));
	 cb->Insert(*new TButtonGadget(CM_AN_ITEM, CM_AN_ITEM));
	 cb->Insert(*new TButtonGadget(CM_EXIT, CM_EXIT));
	 cb->Insert(*new TSeparatorGadget(6));
	 cb->Insert(*new TButtonGadget(CM_MOVEBAR, CM_MOVEBAR));
	 cb->Attr.Id=CM_TOOL_BAR; // attaches check to the CM_TOOL_BAR command in Menu
	 // Add fly-over help hints.
	 cb->SetHintMode(TGadgetWindow::EnterHints);
	 Insert(*cb, TDecoratedFrame::Top);
	 barOnTop = true; // Is the toolbar horizontal on top or vertical along left?
}

Changing The Orientation of The Bar

The command CM_MOVEBAR which is only associated with a button (not a menu item), uses the SetDirection command to change the orientation of the toolbar. Then it inserts the new toolbar into the frame and calls on Layout to show the new position. It then switches the value of barOnTop so the next call will know the current orientation. This command cannot be accessed from a menu, because if the bar is not visible, the command does nothing but cause a crash.

void SDIDecFrame::cmMoveBar ()
{
     // INSERT>> Your code here.
        if (barOnTop)
        {
            cb->SetDirection(TControlBar::Vertical);
            Insert(*cb,TDecoratedFrame::Left);
        }
        else
        {
            cb->SetDirection(TControlBar::Horizontal);
            Insert(*cb,TDecoratedFrame::Top);
        }
        Layout();
        barOnTop = !barOnTop;
}

Adding Your Own Buttons

As you add menu items to your program, you may want to add buttons. Some of the menu choices are seldom used, so if you add a button for these choices you run the risk of overwhelming the toolbar. Once you have decided on those items to be iconized design an icon that is simple and will capture the essence of the choice (this is tough). You will see that the icon which is understandable in the large form created in the resource workshop, is all but indecipherable in the tool box below.

Start the resource workshop and create a new bitmap with the command constant as its identifier. The size of the standard AppExpert icon is 20x20, while the number of colors in these icons is 16. Duplicate these numbers when you create your bitmap or your icon will not line up with the rest of the items in the toolbar.
Next in the c++ ide, add the new item to the toolbar by adding an insert call to the end of the list in the SetupToolBar function.	cb->Insert(*new TButtonGadget(CM_AN_ITEM, CM_AN_ITEM));

ToolBoxes

Introduction

Toolboxes are a variation of a toolbar that can appear anywhere on the screen. When you create the toolbox, the only difference is that you replace the line

    TControlBar* cb = new TControlBar(frame);

with the line

        TToolBox* cb = new TToolBox(this);

. By default this results in a toolbox with two rows and as many columns as you need. If you want only one column, you would substitute

        TToolBox* cb = new TToolBox(this,1);

These setups are fine if you want your toolbox at the left or right. If on the other hand you want your toolbox at the top or bottom of the window you would use the following to get 2 rows with the number of buttons used.

        TToolBox* cb = new TToolBox(this,AS_MANY_AS_NEEDED,2);

The following code shows a toolbox at the left. The value TDecoratedFrame::Left can have the alternate values Right, Top or Bottom.

IDecFrame::SDIDecFrame (TWindow *parent, const char far *title, TWindow *clientWnd, bool trackMenuSelection, TModule *module)
    : TDecoratedFrame(parent, title, clientWnd == 0 ? new TooltestWindow(0, "") : clientWnd, trackMenuSelection, module)
{
    // INSERT>> Your constructor code here.
    TToolBox* cb = new TToolBox(this,1);
    cb->Insert(*new TButtonGadget(CM_FILENEW, CM_FILENEW));
    cb->Insert(*new TButtonGadget(CM_FILEOPEN, CM_FILEOPEN));
    cb->Insert(*new TButtonGadget(CM_FILESAVE, CM_FILESAVE));
    cb->Insert(*new TSeparatorGadget(6));
    cb->Insert(*new TButtonGadget(CM_EDITCUT, CM_EDITCUT));
    cb->Insert(*new TButtonGadget(CM_EDITCOPY, CM_EDITCOPY));
    cb->Insert(*new TButtonGadget(CM_EDITPASTE, CM_EDITPASTE));
    cb->Insert(*new TSeparatorGadget(6));
    cb->Insert(*new TButtonGadget(CM_EDITUNDO, CM_EDITUNDO));
    cb->Insert(*new TSeparatorGadget(6));
    cb->Insert(*new TButtonGadget(CM_EDITFIND, CM_EDITFIND));
    cb->Insert(*new TButtonGadget(CM_EDITFINDNEXT, CM_EDITFINDNEXT)); 
    cb->Insert(*new TSeparatorGadget(6));
    cb->Insert(*new TButtonGadget(CM_AN_ITEM, CM_AN_ITEM));  
    cb->Insert(*new TButtonGadget(CM_EXIT, CM_EXIT));

    // Add fly-over help hints.
    cb->SetHintMode(TGadgetWindow::EnterHints);

    Insert(*cb, TDecoratedFrame::Left);
}

Here we see the toolbox above shown at the bottom or top of the page. Notice how poorly the icon we created shows up in real size.

Creating a Floating Toolbox

Finally, we want to create a floating toolbox. This will be the same as the tool boxes above except it will have its own window that can be relocated, closed and opened again. This is a topic of general interest therefore the notes are stored in the Borland help. Click here to see this file.

Validators

When you have a TEdit window which is supposed to collect a numerical value, you can restrict values typed into this window using a validator. Click here for a discussion of validators.

Splash Windows

For those who want to add a splash window click here.