6.2 The toolbar using

The tool bar creation

Maybe, the most widely used common control is a toolbar. A Windows toolbar common control is a rectangular child window that contains one or more buttons. These buttons can display a bitmap image, a string, or both. When the user chooses a button, it sends a command message to the toolbar's owner window. Typically, the buttons in a toolbar correspond to items in the application's menu; they provide a more direct way for the user to access an application's commands.

The CToolBarCtrl class provides the functionality of the Windows toolbar common control. This control (and therefore the CToolBarCtrl class) is available only to programs running under Windows 95 and Windows NT version 3.51 and later.

CToolBarCtrl objects contain several important internal data structures: a list of button image bitmaps, a list of button label stings, and a list of TBBUTTON structures which associate an image and/or string with the position, style, state, and command ID of the button. Each of the elements of these data structures is referred to by a zero-based index. Before you can use a CToolBarCtrl object, you must set up these data structures. The list of strings can only be used for button labels; you cannot retrieve strings from the toolbar.

To use a CToolBarCtrl object, you will typically follow these steps:

1. Construct the CToolBarCtrl object.

2. Call Create to create the Windows toolbar common control and attach it to the CToolBarCtrl object.

3. If you want bitmap images for buttons, add the button bitmaps to the toolbar by calling AddBitmap. If you want string labels for buttons, add the strings to the toolbar by calling AddString and/or AddStrings.

4. Add button structures to the toolbar by calling AddButtons.

5. If you want tool tips for a toolbar button in an owner window that is not a CFrameWnd, you need to handle the TTN_NEEDTEXT messages in the toolbar's owner window as described in CToolBarCtrl: Handling Tool Tip Notifications. If the parent window of the toolbar is derived from CFrameWnd, tool tips are displayed without any extra effort from you because CFrameWnd provides a default handler.

The Create() function provides the creation of toolbar object:

BOOL CToolBarCtrl::Create( DWORD dwStyle, const RECT& rect, CWnd* pParentWnd, UINT nID );

Parameters

dwStyle   Specifies the toolbar control's style. Toolbars must always have the WS_CHILD style. In addition, you can specify any combination of toolbar styles and window styles as described under Remarks.

rect   Specifies the toolbar control's size and position. (CRect object or a RECT structure)

pParentWnd   Specifies the toolbar control's parent window. It must not be NULL.

nID   Specifies the toolbar control's ID.

You construct a CToolBarCtrl in two steps. First call the constructor, then call Create, which creates the toolbar control and attaches it to the CToolBarCtrl object.

The toolbar control automatically sets the size and position of the toolbar window. The height is based on the height of the buttons in the toolbar. The width is the same as the width of the parent window's client area. The CCS_TOP and CCS_BOTTOM styles determine whether the toolbar is positioned along the top or bottom of the client area. By default, a toolbar has the CCS_TOP style.

Apply the following window styles to a toolbar control: WS_CHILD -  Always, WS_VISIBLE - Usually, WS_DISABLED – Rarely.

Next, you may want to apply one or more of the common control styles:

1. CCS_ADJUSTABLE   Allows toolbars to be customized by the user. If this style is used, the toolbar's owner window must handle the customization notification messages sent by the toolbar.

2. CCS_BOTTOM   Causes the control to position itself at the bottom of the parent window's client area and sets the width to be the same as the parent window's width.

3. CCS_NODIVIDER   Prevents a two-pixel highlight from being drawn at the top of the control.

4. CCS_NOHILITE   Prevents a one-pixel highlight from being drawn at the top of the control.

5. CCS_NOMOVEY   Causes the control to resize and move itself horizontally, but not vertically, in response to a WM_SIZE message. If the CCS_NORESIZE style is used, this style does not apply.

6. CCS_NOPARENTALIGN   Prevents the control from automatically moving to the top or bottom of the parent window. Instead, the control keeps its position within the parent window despite changes to the size of the parent window. If the CCS_TOP or CCS_BOTTOM style is also used, the height is adjusted to the default, but the position and width remain unchanged.

7. CCS_NORESIZE   Prevents the control from using the default width and height when setting its initial size or a new size. Instead, the control uses the width and height specified in the request for creation or sizing.

8. CCS_TOP   Causes the control to position itself at the top of the parent window's client area and sets the width to be the same as the parent window's width. Toolbars have this style by default.

Finally, you may want to apply one or both of the following toolbar control styles to a toolbar control:

9. TBSTYLE_TOOLTIPS   Causes the toolbar to create and manage a tool tip control. A tool tip is a small pop-up window that contains a line of text describing a toolbar button. It appears only when the user puts the cursor on a toolbar button and leaves it there for approximately one-half second. The tool tip is displayed near the cursor. If you use this style, you must handle tool tip notifications.

10. TBSTYLE_WRAPABLE   Creates a toolbar control that can have multiple lines of buttons. Toolbar buttons can "wrap" to the next line when the toolbar becomes too narrow to include all buttons on the same line.

The toolbar, constructed after Create() call, isn’t yet initiated and can’t be used. To make that, it’s need to make two additional actions: At first, the buttons must be added, at second, you must add the image of every button of such toolbar. Also, the text label can be linked to the every image.

Adding button to the toolbar

The buttons are added by AddButtons() function:

BOOL CToolBarCtrl::AddButtons( int nNumButtons, LPTBBUTTON lpButtons );

Parameters:

nNumButtons   Number of buttons to add.

lpButtons   Address of an array of TBBUTTON structures that contains information about the buttons to add. There must be the same number of elements in the array as buttons specified by nNumButtons

The lpButtons pointer points to an array of TBBUTTON structures. Each TBBUTTON structure associates the button being added with the button's style, image and/or string, command ID, state, and user-defined data:

typedef struct _TBBUTTON {

int iBitmap; // zero-based index of button image

int idCommand; // command to be sent when button pressed

BYTE fsState; // button state--see below

BYTE fsStyle; // button style--see below

DWORD dwData; // application-defined value

int iString; // zero-based index of button label string

} TBBUTTON;

The members are as follows:

iBitmap   Zero-based index of button image. NULL if no image for this button.

idCommand   Command identifier associated with the button. This identifier is sent in a WM_COMMAND message when the button is chosen. If the fsStyle member has the TBSTYLE_SEP value, this member must be zero.

fsState   Button state flags. It can be a combination of the values listed below:

TBSTATE_CHECKED   The button has the TBSTYLE_CHECKED style and is being pressed.

TBSTATE_ENABLED   The button accepts user input. A button that does not have this state does not accept user input and is grayed.

TBSTATE_HIDDEN   The button is not visible and cannot receive user input.

TBSTATE_INDETERMINATE   The button is grayed.

TBSTATE_PRESSED   The button is being pressed.

TBSTATE_WRAP   A line break follows the button. The button must also have the TBSTATE_ENABLED state.

fsStyle   Button style. It can be a combination of the values listed below:

TBSTYLE_BUTTON   Creates a standard push button.

TBSTYLE_CHECK   Creates a button that toggles between the pressed and unpressed states each time the user clicks it. The button has a different background color when it is in the pressed state.

TBSTYLE_CHECKGROUP   Creates a check button that stays pressed until another button in the group is pressed.

TBSTYLE_GROUP   Creates a button that stays pressed until another button in the group is pressed.

TBSTYLE_SEP   Creates a separator, providing a small gap between button groups. A button that has this style does not receive user input.

dwData   User-defined data.

iString   Zero-based index of the string to use as the button's label. NULL if there is no string for this button.

The image and/or string whose index you provide must have previously been added to the toolbar control's list using AddBitmap, AddString, and/or AddStrings.

Adding images to the toolbar

Adding images is provided by AddBitmap function. The image of button is a 16x15 pixels, the button size 24x22. To the toolbar there is linked only one image, which contains the images of all buttons. For example, six buttons has size 16x6 = 96 pixels. Default name of file to save the buttons images is TOOLBAR.BMP.

int CToolBarCtrl::AddBitmap( int nNumButtons, UINT nBitmapID );

int CToolBarCtrl::AddBitmap( int nNumButtons, CBitmap* pBitmap );

Return Value: Zero-based index of the first new image if successful; otherwise – 1.

Parameters:

nNumButtons   Number of button images in the bitmap.

nBitmapID   Resource identifier of the bitmap that contains the button image or images to add.

pBitmap   Pointer to the CBitmap object that contains the button image or images to add.

Additional functions to work with toolbar

After the toolbar initiation, the size is set accordingly to the size of parent window. If to change the window size, the toolbar dimension will not change. That problem is decided by AutoSize() function:

void CToolBarCtrl::AutoSize( ); // Call this function to resize the entire toolbar control. You should call this function when the size of the parent window changes or when the size of the toolbar changes (such as when you set the button or bitmap size, or add strings).