Class ICustToolbar
See Also: Custom Controls. Class ToolItem, Class MacroButtonData, Class CUIFrameMsgHandler, Class ICustStatusEdit, Class ICustStatus, Class ICustButton.
class ICustToolbar : public ICustomControl
Description:
This control allows the creation of toolbars containing buttons (push, check, and fly-offs), status fields, separators (spacers), and other Windows or user defined controls. Note: The standard size for 3ds max toolbar button icons is 16x15.
In 3ds max 3.0 and later toolbars may have multiple rows, or appear vertically. They may also have macro buttons (added with the MacroButtonData class) which may have icons or text.
To initialize the pointer to the control call:
Prototype:
ICustToolbar *GetICustToolbar(HWND hCtrl);
To release the control call:
Prototype:
ReleaseICustToolbar(ICustToolbar *ict);
The value to use in the Class field of the Custom Control Properties dialog is: CustToolbar
Note: The TB_RIGHTCLICK message is sent when the user right clicks in open space on a toolbar:
Also Note: To add tooltips to the toolbar controls you can do so by capturing the WM_NOTIFY message in the dialog proc. For complete sample code see \MAXSDK\SAMPLES\HOWTO\CUSTCTRL\CUSTCTRL.CPP. The specific message is processed as shown below.
case WM_NOTIFY:
// This is where we provide the tooltip text for the
// toolbar buttons...
if(((LPNMHDR)lParam)->code == TTN_NEEDTEXT) {
LPTOOLTIPTEXT lpttt;
lpttt = (LPTOOLTIPTEXT)lParam;
switch (lpttt->hdr.idFrom) {
case ID_TB_1:
lpttt->lpszText = _T("Do Nothing Up");
break;
case ID_TB_2:
lpttt->lpszText = _T("Do Nothing Down");
break;
case ID_TB_3:
lpttt->lpszText = _T("Do Nothing Lock");
break;
case IDC_BUTTON1:
if (to->custCtrlButtonC->IsChecked())
lpttt->lpszText = _T("Button Checked");
else
lpttt->lpszText = _T("Button Un-Checked");
break;
};
}
break;
Methods:
Prototype:
virtual void SetImage(HIMAGELIST hImage)=0;
Remarks:
This method establishes the image list used to display images in the toolbar.
Parameters:
HIMAGELIST hImage
The image list. An image list is a collection of same-sized images, each of which can be referred to by an index. Image lists are used to efficiently manage large sets of icons or bitmaps in Windows. All images in an image list are contained in a single, wide bitmap in screen device format. An image list may also include a monochrome bitmap that contains masks used to draw images transparently (icon style). The Windows API provides image list functions, which enable you to draw images, create and destroy image lists, add and remove images, replace images, and merge images.
Prototype:
virtual void AddTool(const ToolItem& entry, int pos=-1)=0;
Remarks:
The developer calls this method once for each item in the toolbar. The items appear in the toolbar from left to right in the order that they were added using this method. (Note that this method adds tools to the custom toolbar and not the 3ds max toolbar).
Parameters:
const ToolItem& entry
Describes the item to add to the toolbar.
int pos=-1
Controls where the added tool is inserted. The default of -1 indicates the control will be added at the right end of the toolbar.
Prototype:
virtual void AddTool2(ToolItem& entry, int pos=-1)=0;
Remarks:
This method is available in release 3.0 and later only.
Currently this method is identical to the AddTool() method.
Parameters:
ToolItem& entry
Describes the item to add to the toolbar.
int pos=-1
Controls where the added tool is inserted. The default of -1 indicates the control will be added at the right end of the toolbar.
Prototype:
virtual void DeleteTools(int start, int num=-1)=0;
Remarks:
This method is used to delete tools from the toolbar.
Parameters:
int start
Specifies which tool is the first to be deleted.
int num=-1
Specifies the number of tools to delete. If this parameter is -1 (the default) it deletes 'start' through count-1 tools.
Prototype:
virtual void SetTopBorder(BOOL on)=0;
Remarks:
Passing TRUE to this method draws a border above the toolbar. You can see the appearance of the top border in the sample toolbar shown above. If this is set to FALSE, the border is not drawn
Parameters:
BOOL on
TRUE to draw the border; FALSE for no border.
Prototype:
virtual void SetBottomBorder(BOOL on)=0;
Remarks:
Passing TRUE to this method draws a border beneath the toolbar. You can see the appearance of the bottom border in the sample toolbar shown above. If this is set to FALSE, the border is not drawn.
Parameters:
BOOL on
TRUE to draw the border; FALSE for no border.
Prototype:
virtual int GetNeededWidth(int rows)=0;
Remarks:
This method is available in release 3.0 and later only.
Returns the width needed for specified number of rows.
Parameters:
int rows
The number of rows.
Prototype:
virtual void SetNumRows(int rows)=0;
Remarks:
This method is available in release 3.0 and later only.
Sets the number of rows that the toolbar may hold.
Parameters:
int rows
The number of rows to set.
Prototype:
virtual ICustButton *GetICustButton(int id)=0;
Remarks:
This method is used to return a pointer to one of the toolbar's buttons. Using this pointer you can call methods on the button. If you use this method, you must release the control after you are finished with it.
Parameters:
int id
Specifies the id of the toolbar button.
Return Value:
A pointer to one of the toolbar's buttons. If the button is not found it returns NULL. See Class ICustButton.
Prototype:
virtual ICustStatus *GetICustStatus(int id)=0;
Remarks:
This method is used to return a pointer to one of the toolbars status controls. Using this pointer you can call methods on the status control. If you use this method, you must release the control after you are finished with it.
Parameters:
int id
Specifies the id of the toolbar button.
Return Value:
A pointer to one of the toolbars status controls. See Class ICustStatus.
Prototype:
virtual ICustStatusEdit *GetICustStatusEdit(int id)=0;
Remarks:
This method is available in release 3.0 and later only.
This method is used to return a pointer to the custom status edit control whose id is passedIf you use this method, you must release the control after you are finished with it. See Class ICustStatusEdit.
Parameters:
int id
Specifies the id of the toolbar button.
Prototype:
virtual HWND GetItemHwnd(int id)=0;
Remarks:
Returns the handle to the toolbar item whose ID is passed.
Parameters:
int id
Specifies the id of the toolbar button.
Prototype:
virtual int GetNumItems()=0;
Remarks:
This method is available in release 2.0 and later only.
Returns the number of items in the toolbar.
Prototype:
virtual int GetItemID(int index)=0;
Remarks:
This method is available in release 2.0 and later only.
Each item in the toolbar has an ID. When items are programatically added to the toolbar via Class ToolButtonItem an ID is passed to the ToolButtonItem constructor. This method returns the ID for the specified item in the toolbar.
Parameters:
int index
Specifies which toolbar item to return the id of. This is an index between 0 and GetNumItems()-1.
Return Value:
When the button is added using Class ToolButtonItem this is the id that is part of that structure. When the user operates a tool the dialog proc get a WM_COMMAND message and this is also the id in LOWORD(wParam).
Prototype:
virtual int FindItem(int id)=0;
Remarks:
This method is available in release 2.0 and later only.
Returns the index into the list of toolbar entries of the item whose id is passed.
Parameters:
int id
The id of the control to find.
Prototype:
virtual void DeleteItemByID(int id)=0;
Remarks:
This method is available in release 2.0 and later only.
Deletes the toolbar item whose id is passed.
Parameters:
int id
The id of the control to delete.
Prototype:
virtual void LinkToCUIFrame(HWND hCUIFrame, CUIFrameMsgHandler *msgHandler)=0;
Remarks:
This method is available in release 3.0 and later only.
This method links this toolbar to the CUI frame whose window handle and message handler are passed.
Parameters:
HWND hCUIFrame
The window handle of the CUI frame to link this toolbar to.
CUIFrameMsgHandler *msgHandler
Points to the message handler for the CUI frame. See Class CUIFrameMsgHandler.
Prototype:
virtual void GetFloatingCUIFrameSize(SIZE *sz, int rows=1)=0;
Remarks:
This method is available in release 4.0 and later only.
This method allows you to obtain the size of the floating CUI frame.
Parameters:
SIZE *sz
The size of the floating frame.
int rows=1
The number of rows displayed in the floating frame.
Prototype:
virtual void ResetIconImages() = 0;
Remarks:
This method is available in release 4.0 and later only.
This resets the icons in the toolbar. This tells all the buttons in this toolbar to delete their icon image cache. If a plug-in has created a toolbar with any MaxBmpFileIcons on it, it should register a callback for color changing, and call this method on the toolbar. See Structure NotifyInfo for registering the color change callback.