modula-2 home

  Win32 API  


App Part 3: Tool and Status bars

Example: app_three


An IMPORTANT Word on Common Controls

As with all common controls, you must call InitCommonControls(), which you import from the COMMCTRL module, BEFORE you try and use them. Note that InitCommonControls() is an older API, and for more control you can use InitCommonControlsEx() which is also required for the most recent common controls. However since I'm not using any of the advanced features, InitCommonControls() is adequate and simpler.


You can create a toolbar using CreateToolbarEx() but I'm not going to, so there. First thing you need to do is actually create the toolbar...

    hTool := CreateWindowEx(0, TOOLBARCLASSNAME, "",
                            WS_CHILD BOR WS_VISIBLE, 0, 0, 0, 0,
                            hwnd, CAST(HMENU,IDC_MAIN_TOOL),Instance, NIL)

That's simple enough, TOOLBARCLASSNAME is a constant imported from COMMCTRL. hwnd is the parent window, the one you want to put the toolbar in. IDC_MAIN_TOOL is an identifier that you can use later to get the HWND of the toolbar using GetDlgItem(), if you so desire.

    (* Send the TB_BUTTONSTRUCTSIZE message, which is required for
       backward compatibility. *)

This message is required to let the system figure out which version of the common controls library you are using. Since new versions add new stuff to the structure, by giving it the size it can figure out what behaviour you are expecting.

Toolbar buttons

Button bitmaps on basic toolbars come in two varieties, standard buttons that are provided by comctl32, and user defined buttons that you create yourself.

NOTE: Buttons and bitmaps are added to toolbars seperately... first you add a list of images to use, and THEN you add a list of buttons, and telling it which button uses which image.

Adding Standard Buttons

Now that we have a toolbar created, we need to add some buttons to it. The most common bitmaps are available in the common control library itself, so we don't need to recreate them or add them to every exe that uses them.

First we have declare a variables as type ARRAY OF TBBUTTONand a variable of type TBADDBITMAP

    tbb  : ARRAY [0..3] OF TBBUTTON;
    tbab : TBADDBITMAP;
And then we add the standard bitmaps to the toolbar, using the imagelist predefined in the common control library...
    tbab.hInst := HINST_COMMCTRL;
    tbab.nID   := IDB_STD_SMALL_COLOR;
    SendMessage(hTool, TB_ADDBITMAP, 0, CAST(LPARAM,ADR(tbab)))

Now that we have our images loaded up, we can add some buttons that use them...

    FillMemBYTE(tbb, SIZE(tbb), 0);
    tbb[0].iBitmap   := STD_FILENEW;
    tbb[0].fsState   := TBSTATE_ENABLED;
    tbb[0].fsStyle   := TBSTYLE_BUTTON;
    tbb[0].idCommand := ID_FILE_NEW;

    tbb[1].iBitmap   := STD_FILEOPEN;
    tbb[1].fsState   := TBSTATE_ENABLED;
    tbb[1].fsStyle   := TBSTYLE_BUTTON;
    tbb[1].idCommand := ID_FILE_OPEN;

    tbb[2].iBitmap   := STD_FILESAVE;
    tbb[2].fsState   := TBSTATE_ENABLED;
    tbb[2].fsStyle   := TBSTYLE_BUTTON;
    tbb[2].idCommand := ID_FILE_SAVEAS;


Here we've added a New, Open and Save As button using the standard images, which is always a good idea since people are used to seeing them and they know what they mean.

The indexes of each image in the imagelist are defined in the COMMCTRL modula and are listed in MSDN.

We have assigned each button an ID (ID_FILE_NEW etc...) which is identical to the IDs of the equivalent menu items. These buttons will generate WM_COMMAND messages identical to the menu, so no extra processing is required! If we were adding a button for a command that didn't already have a menu item, we would simply pick a new ID for it and add a handler to WM_COMMAND.

If you're wondering what's up with the funky wParam I passed to TB_ADDBUTTONS it's doing a calculation of the number of buttons in the array tbb so that we don't need to hardcode a value. If I put in 3 instead it would still be correct, but as soon as I added another button I'd have to change it to 4 and in programming that's bad... you want one change to cause as few other changes as possible. For example if the SIZE(TBBUTTON) was 16 bytes (I made that up, it actually varies by platform) then since we have 3 buttons the SIZE(tbb) would be 16 * 3 or 48. Therefor 48/16 gives us the number of buttons, 3.

Status bars

Something often found in apps with toolbars are status bars, the little things at the bottom of the window that display information. They're pretty simple to use, just create...

     hStatus := CreateWindowEx(0, STATUSCLASSNAME, "",
                     0, 0, 0, 0, hwnd,
                     CAST(HMENU,IDC_MAIN_STATUS), Instance, NIL);

And then (optionally) set the number of sections that you want. If you don't set any, it will simply have one section using the entire width of the bar, and you can set and retreive the text with SetWindowText() as with many other controls. For more than one part, you need to give the widths of each section, and then use SB_SETTEXT to set the text of each one.

To define the widths, we have declared an array of INTEGERSs, where each value is the width in pixels of a section. If you want one section to use up any remaining space, set it's width to -1.

   TYPE intarray = ARRAY [0..1] OF INTEGER;
   CONST statwidths = intarray{100,-1};

This is the code to set the width of the two sections:

     SendMessage(hStatus, SB_SETPARTS,
                 SIZE(statwidths) DIV SIZE(INTEGER),

     SendMessage(hStatus, SB_SETTEXT, 0, CAST(LPARAM,ADR("Hi there :)")))

The wParam again is our calculation of how many elements are in the array. Once we're done adding sections, we set the first one (index 0) to see it in action.

Proper Sizing

Unlike menus, tool and status bars are seperate controls that live inside the parent window's client area. Therefor if we just leave our WM_SIZE code from before, they are going to overlap with the edit control we added in the previous examples. This is a simple matter to correct... in WM_SIZE, we move the tool and status bars into position, and then subtract their heights and positions from the client area so that we can move our edit control to fill the remaining space...

We have defined the following variables:

    hEdit,hStatus,hTool                   : HWND;
    rcClient,rcStatus,rcTool              : RECT;
    iEditHeight,iStatusHeight,iToolHeight : INTEGER;

And this is the code to size the Tool window, Status bar window end Edit control window when our window procedure receives the WM_SIZE message:

    (* Size toolbar and get height *)

    hTool := GetDlgItem(hwnd, IDC_MAIN_TOOL);
    SendMessage(hTool, TB_AUTOSIZE, 0, 0);

    GetWindowRect(hTool, rcTool);
    iToolHeight := rcTool.bottom -;

    (* Size status bar and get height *)

    hStatus := GetDlgItem(hwnd, IDC_MAIN_STATUS);
    SendMessage(hStatus, WM_SIZE, 0, 0);

    GetWindowRect(hStatus, rcStatus);
    iStatusHeight := rcStatus.bottom -;

    (* Calculate remaining height and size edit *)

    GetClientRect(hwnd, rcClient);

    iEditHeight := rcClient.bottom - iToolHeight - iStatusHeight;

    hEdit := GetDlgItem(hwnd, IDC_MAIN_EDIT);
    SetWindowPos(hEdit, NIL, 0, iToolHeight, rcClient.right,
                 iEditHeight, SWP_NOZORDER);

Unfortunately it's a somewhat long code snippet, but it's quite simple... toolbars will auto position themselves when sent the TB_AUTOSIZE message, and status bars will do the same if you send them WM_SIZE (the common control libraries are not known for consistancy).


Copyright © 1998-2011, Brook Miles. All rights reserved. Adapted for Modula-2 by Frank Schoonjans, with permission.