#include <custcont.h>

Class Description

See also: Class ICustomControl, Custom User Interface Controls, Class ICustToolbar, Class FlyOffData, Class DADMgr, Class MAXBmpFileIcon.

Description:: Custom buttons may be one of two different forms. A Check button (which stays pressed in until the user clicks on it again), or a Pick button (which pops back out as soon as it is released). Buttons may be implemented as a Fly offs. A fly off offers several alternative buttons which fly out from the button after it is press and held briefly.

The buttons may contain text or graphic images. Fly off buttons only use graphic images. The plug-in developer has control over the appearance of the button in each of its four states (Enabled&Out, Enabled&In, Disabled&Out, Disabled&In).

Note: When the user presses a button a WM_MENUSELECT message is sent so that the client can display a status prompt describing the function of the tool. The fuFlags parameter is set to this value: CMF_TOOLBUTTON.

In 3dsmax version 4.0 you can remove borders from an ICustButton;

ICustButton *cb = ();

cb->Execute(I_EXE_CB_NO_BORDER);

To initialize the pointer to the control call:
ICustButton *GetICustButton(HWND hCtrl);
To release the control call:
ReleaseICustButton(ICustButton *ics);
The value to use in the Class field of the Custom Control Properties dialog is: CustButton

Inheritance diagram for ICustButton:

Public Member Functions
virtual void	GetText (MCHAR *text, int ct)=0

virtual void	SetText (const MCHAR *text)=0

virtual void	GetText (MSTR &text) const =0

virtual int	GetTextLength () const =0

virtual void	SetImage (HIMAGELIST hImage, int iOutEn, int iInEn, int iOutDis, int iInDis, int w, int h)=0

virtual void	SetIcon (MaxBmpFileIcon *pIcon, int w, int h)=0

virtual void	SetInIcon (MaxBmpFileIcon *pInIcon, int w, int h)=0

virtual void	SetIconByName (const MSTR &iconName, int iconWidth=0, int iconHeight=0)=0

virtual MSTR	GetIconName () const =0

virtual void	SetType (CustButType type)=0

virtual void	SetFlyOff (int count, FlyOffData *data, int timeOut, int init, int dir=FLY_VARIABLE, int columns=1)=0

virtual void	SetFlyOffIconsByName (const FlyOffIconList &flyOffIcons, int timeOut, int init, int dir=FLY_VARIABLE, int columns=1)=0

virtual FlyOffIconList	GetFlyOffIconNames () const =0

virtual void	SetCurFlyOff (int f, BOOL notify=FALSE)=0

virtual int	GetCurFlyOff ()=0

virtual BOOL	IsChecked ()=0

virtual void	SetCheck (BOOL checked)=0

virtual void	SetCheckHighlight (BOOL highlight)=0

virtual void	SetButtonDownNotify (BOOL notify)=0

virtual void	SetRightClickNotify (BOOL notify)=0

virtual void	SetHighlightColor (COLORREF clr)=0

virtual COLORREF	GetHighlightColor ()=0

virtual void	SetDADMgr (DADMgr *dad)=0

virtual DADMgr *	GetDADMgr ()=0

virtual void	SetMacroButtonData (MacroButtonData *md)=0

virtual MacroButtonData *	GetMacroButtonData ()=0

virtual MAX_DEPRECATED void	SetDisplayProc (PaintProc *proc) MAX_SEALED

virtual const MCHAR *	GetCaptionText (void)=0

virtual bool	SetCaptionText (const MCHAR *text)=0

virtual void	UseIconAndText (bool sw=true)=0

Public Member Functions inherited from ICustomControl
virtual HWND	GetHwnd ()=0

virtual void	Enable (BOOL onOff=TRUE)=0

virtual void	Disable ()=0

virtual BOOL	IsEnabled ()=0

virtual void	Enable2 (BOOL onOff=TRUE)=0

virtual INT_PTR	Execute (int cmd, ULONG_PTR arg1=0, ULONG_PTR arg2=0, ULONG_PTR arg3=0)

virtual void	SetTooltip (bool bEnable, const MCHAR *text)=0
	Sets a tooltip for the custom control. More...

CoreExport void	UpdateEnableState (Animatable *anim, int subNum)
	Helper function to disable or enable this UI control based on whether the Animatable associated with it is keyframable or not (locked parameter or scripted parameters are not keyframable). More...

Public Member Functions inherited from InterfaceServer
virtual UtilExport	~InterfaceServer ()
	Destructor. More...

virtual UtilExport BaseInterface *	GetInterface (Interface_ID id)

Additional Inherited Members
Static Public Member Functions inherited from MaxHeapOperators
static UtilExport void *	operator new (size_t size)
	Standard new operator used to allocate objects If there is insufficient memory, an exception will be thrown. More...

static UtilExport void *	operator new (size_t size, const std::nothrow_t &e)
	Standard new operator used to allocate objects if there is insufficient memory, NULL will be returned. More...

static UtilExport void *	operator new (size_t size, const char *filename, int line)
	New operator used to allocate objects that takes the filename and line number where the new was called If there is insufficient memory, an exception will be thrown. More...

static UtilExport void *	operator new (size_t size, int block_type, const char *filename, int line)
	New operator used to allocate objects that takes the type of memory, filename and line number where the new was called If there is insufficient memory, an exception will be thrown. More...

static UtilExport void *	operator new (size_t size, const std::nothrow_t &e, const char *filename, int line)
	New operator used to allocate objects that takes the filename and line number where the new was called If there is insufficient memory, NULL will be returned. More...

static UtilExport void *	operator new (size_t size, unsigned long flags)
	New operator used to allocate objects that takes extra flags to specify special operations If there is insufficient memory, an exception will be thrown. More...

static UtilExport void *	operator new (size_t size, const std::nothrow_t &e, unsigned long flags)
	New operator used to allocate objects that takes extra flags to specify special operations If there is insufficient memory, NULL will be returned. More...

static UtilExport void *	operator new[] (size_t size)
	New operator used to allocate arrays of objects If there is insufficient memory, an exception will be thrown. More...

static UtilExport void *	operator new[] (size_t size, const std::nothrow_t &e)
	New operator used to allocate arrays of objects If there is insufficient memory, NULL will be returned. More...

static UtilExport void *	operator new[] (size_t size, const char *filename, int line)
	New operator used to allocate arrays of objects If there is insufficient memory, an exception will be thrown. More...

static UtilExport void *	operator new[] (size_t size, int block_type, const char *filename, int line)
	New operator used to allocate arrays of objects. More...

static UtilExport void *	operator new[] (size_t size, const std::nothrow_t &e, const char *filename, int line)
	New operator used to allocate arrays of objects If there is insufficient memory, NULL will be returned. More...

static UtilExport void *	operator new[] (size_t size, unsigned long flags)
	New operator used to allocate arrays of objects If there is insufficient memory, an exception will be thrown. More...

static UtilExport void *	operator new[] (size_t size, const std::nothrow_t &e, unsigned long flags)
	New operator used to allocate arrays of objects If there is insufficient memory, NULL will be returned. More...

static UtilExport void	operator delete (void *ptr)
	Standard delete operator used to deallocate an object If the pointer is invalid, an exception will be thrown. More...

static UtilExport void	operator delete (void *ptr, const std::nothrow_t &e)
	Standard delete operator used to deallocate an object If the pointer is invalid, nothing will happen. More...

static UtilExport void	operator delete (void ptr, const char filename, int line)
	Delete operator used to deallocate an object that takes the filename and line number where the delete was called If the pointer is invalid, an exception will be thrown. More...

static UtilExport void	operator delete (void ptr, int block_type, const char filename, int line)
	Delete operator used to deallocate an object that takes the type of memory, filename and line number where the delete was called If the pointer is invalid, an exception will be thrown. More...

static UtilExport void	operator delete (void ptr, const std::nothrow_t &e, const char filename, int line)
	Delete operator used to deallocate an object that takes the filename and line number where the delete was called If the pointer is invalid, nothing will happen. More...

static UtilExport void	operator delete (void *ptr, unsigned long flags)
	Delete operator used to deallocate an object that takes extra flags to specify special operations If the pointer is invalid, an exception will be thrown. More...

static UtilExport void	operator delete (void *ptr, const std::nothrow_t &e, unsigned long flags)
	Delete operator used to deallocate an object that takes extra flags to specify special operations If the pointer is invalid, nothing will happen. More...

static UtilExport void	operator delete[] (void *ptr)
	Standard delete operator used to deallocate an array of objects If the pointer is invalid, an exception will be thrown. More...

static UtilExport void	operator delete[] (void *ptr, const std::nothrow_t &e)
	Standard delete operator used to deallocate an array of objects If the pointer is invalid, nothing will happen. More...

static UtilExport void	operator delete[] (void ptr, const char filename, int line)
	Delete operator used to deallocate an array of objects that takes the filename and line number where the delete was called If the pointer is invalid, an exception will be thrown. More...

static UtilExport void	operator delete[] (void ptr, int block_type, const char filename, int line)
	Delete operator used to deallocate an array of objects that takes the type of memory, filename and line number where the delete was called If the pointer is invalid, an exception will be thrown. More...

static UtilExport void	operator delete[] (void ptr, const std::nothrow_t &e, const char filename, int line)
	Delete operator used to deallocate an array of objects that takes the filename and line number where the delete was called If the pointer is invalid, nothing will happen. More...

static UtilExport void	operator delete[] (void *ptr, unsigned long flags)
	Delete operator used to deallocate an array of objects that takes extra flags to specify special operations If the pointer is invalid, an exception will be thrown. More...

static UtilExport void	operator delete[] (void *ptr, const std::nothrow_t &e, unsigned long flags)
	Delete operator used to deallocate an array of objects that takes extra flags to specify special operations If the pointer is invalid, an exception will be thrown. More...

static UtilExport void *	operator new (size_t size, void *placement_ptr)
	Placement new operator. More...

static UtilExport void	operator delete (void ptr, void placement_ptr)
	Placement delete operator. More...

static UtilExport void *	aligned_malloc (size_t size, size_t alignment)
	Allocates memory on a specified alignment boundary. More...

static UtilExport void *	aligned_realloc (void *ptr, size_t size, size_t alignment)
	Reallocates memory on a specified alignment boundary. More...

static UtilExport void	aligned_free (void *ptr)
	Frees a block of memory that was allocated with aligned_malloc/aligned_realloc. More...

Member Function Documentation

virtual void GetText	(	MCHAR *	text,
		int	ct
	)

pure virtual

Remarks: This retrieves the text displayed by the button.

Parameters

text	Storage for the text to retrieve.
ct	Specifies the maximum length of the string returned.

virtual void SetText ( const MCHAR * text )

pure virtual

Remarks: This specifies the text displayed by the button.

Parameters

text	The text to be displayed by the button.

virtual void GetText ( MSTR & text ) const

pure virtual

Remarks: This retrieves the text entered into the control.

Parameters

text	Storage for the text to retrieve.

virtual int GetTextLength ( ) const

pure virtual

Remarks: This retrieves the length of the text entered into the control. It returns the length of the text in characters (so without the terminating NULL). Note that this value may be higher than the actual length of the text when it contains multi-byte characters.

virtual void SetImage	(	HIMAGELIST	hImage,
		int	iOutEn,
		int	iInEn,
		int	iOutDis,
		int	iInDis,
		int	w,
		int	h
	)

pure virtual

Remarks: This method is used to establish the images used for the buttons.

Parameters

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. The next four parameters (iOutEn, iInEn, iOutDis, iInDis) are indices into the image list. They indicate which images to use for each of the four possible button states. You may specify a unique image for each one of these states by passing a different index for each state. Or you may supply a single image to be used for all the states by specifying the same index four times.
iOutEn	Out&Enabled.
iInEn	In&Enabled.
iOutDis	Out&Disabled.
iInDis	In&Disabled.
w	The width of the button image.
h	The height of the button image.

virtual void SetIcon	(	MaxBmpFileIcon *	pIcon,
		int	w,
		int	h
	)

pure virtual

Remarks: This sets the icon image used for a button.

Parameters

pIcon	Points to the icon.
w	The width of the button image.
h	The height of the button image.

virtual void SetInIcon	(	MaxBmpFileIcon *	pInIcon,
		int	w,
		int	h
	)

pure virtual

Remarks: This sets the icon image used when a button is pressed.

Parameters

pInIcon	Points to the icon.
w	The width of the button image.
h	The height of the button image.

virtual void SetIconByName	(	const MSTR &	iconName,
		int	iconWidth = `0`,
		int	iconHeight = `0`
	)

pure virtual

Remarks: Sets a multi-resolution icon to the button.

Parameters

iconName	The name of the icon.
iconWidth	The default width of the button icon at 100% dpi scale. An iconWidth of 0 will use the default toolbar button image size as default. This value will internally get scaled according to the current dpi setting.
iconHeight	The default height of the button icon at 100% dpi scale. An iconHeight of 0 will use the default toolbar button image size as default. This value will internally get scaled according to the current dpi setting.

See also: QIcon MaxSDK::LoadMaxMultiResIcon( const QString& iconName )

virtual MSTR GetIconName ( ) const

pure virtual

Remarks: Returns the name of the multi-resolution icon assigned to the button.

See also: void SetIconByName( const MSTR& iconName )

virtual void SetType ( CustButType type )

pure virtual

Remarks: This method sets the button type.

Parameters

type	One of the following values: CBT_PUSH A Push button pops back out as soon as it is released. CBT_CHECK. A Check button stays pressed in until the user clicks on it again.

virtual void SetFlyOff	(	int	count,
		FlyOffData *	data,
		int	timeOut,
		int	init,
		int	dir = `FLY_VARIABLE`,
		int	columns = `1`
	)

pure virtual

Remarks: This method sets the button to work as a fly off control.

Parameters

count	The number of buttons in the fly off.
data	An array of instances of the class FlyOffData . This class uses four indices into the image list to describe the button in each of the possible states: Out&Enabled, In&Enabled, Out&Disabled and In&Disabled. In the simple case, where all the buttons have the same image, you can do the following: FlyOffData fod[3] = { // A three button flyoff { 0,0,0,0 }, // The first button uses a single image. { 1,1,1,1 }, // So does the second button... { 2,2,2,2 }, // So does the third... }; Each button will use the same images regardless of its pressed in / disabled state. Note the button is automatically drawn pushed in (i.e. shaded lighter) when the user is dragging the cursor over the button, but the actual image on the button is not changed. If you require different images for these states, supply different indices into the image list for each. See the sample program /MAXSDK/SAMPLES/HOWTO/CUSTCTRL/CUSTCTRL.CPP for an example of how this is done.
timeOut	This is the time in milliseconds the button must be held pressed before the fly off appears. You may specify 0 if you want the buttons to fly off immediately. To retrieve the value that 3ds Max uses internally for its flyoffs use a method of Class Interface called GetFlyOffTime(). This returns a value in milliseconds.
init	This is the initial button displayed.
dir	This parameter is optional. It is used to indicate which direction the buttons should fly off. The choices for direction are: FLY_VARIABLE The default. The system will determine the direction of the fly off. FLY_UP The buttons fly off above. FLY_DOWN The buttons fly off beneath. FLY_HVARIABLE The buttons will fly off either left or right with the system determining the direction. FLY_LEFT The buttons fly off to the left. FLY_RIGHT The buttons fly off to the right.
columns

virtual void SetFlyOffIconsByName	(	const FlyOffIconList &	flyOffIcons,
		int	timeOut,
		int	init,
		int	dir = `FLY_VARIABLE`,
		int	columns = `1`
	)

pure virtual

Remarks: This method sets the button to work as a fly off control.

Parameters

flyOffIcons	A FlyOffIconList of icon names. The icon names are used to create multi-resolution icons for the buttons in the fly off control. A simple fly off can be defined by: FlyOffIconList flyOffIcons; // A vector of MSTR's flyOffIcons.push_back( L"MyPlugin/FlyOffOption1" ); // first icon name flyOffIcons.push_back( L"MyPlugin/FlyOffOption2" ); // second icon name custButton->SetFlyOffIconNames( flyOffIcons, GetCOREInterface()->GetFlyOffTime(), 0, FLY_DOWN );
timeOut	This is the time in milliseconds the button must be held pressed before the fly off appears. You may specify 0 if you want the buttons to fly off immediately. To retrieve the value that 3ds Max uses internally for its flyoffs use a method of Class Interface called GetFlyOffTime(). This returns a value in milliseconds.
init	This is the initial button displayed.
dir	This parameter is optional. It is used to indicate which direction the buttons should fly off. The choices for direction are: FLY_VARIABLE The default. The system will determine the direction of the fly off. FLY_UP The buttons fly off above. FLY_DOWN The buttons fly off beneath. FLY_HVARIABLE The buttons will fly off either left or right with the system determining the direction. FLY_LEFT The buttons fly off to the left. FLY_RIGHT The buttons fly off to the right.
columns

See also: QIcon MaxSDK::LoadMaxMultiResIcon( const QString& iconName )

virtual FlyOffIconList GetFlyOffIconNames ( ) const

pure virtual

Remarks: Returns a list of the multi-resolution icon names used in the button fly off control.

See also: void SetFlyOffIconsByName( const FlyOffIconList& flyOffIcons, int timeOut, int init, int dir=FLY_VARIABLE, int columns=1 )

virtual void SetCurFlyOff	(	int	f,
		BOOL	notify = `FALSE`
	)

pure virtual

Remarks: This method establishes which button is displayed by passing its index.

Parameters

f	The index of the flyoff button to display.
notify	This indicates if the call to this method should notify the dialog proc. If TRUE it is notified; otherwise it isn't.

virtual int GetCurFlyOff ( )

pure virtual

Remarks: Returns the index of the button which is currently displayed.

virtual BOOL IsChecked ( )

pure virtual

Remarks: Determines if the button is checked. This method returns TRUE if the check button is currently in the In state (i.e. checked) and FALSE otherwise.

virtual void SetCheck ( BOOL checked )

pure virtual

Remarks: Passing TRUE to this method sets the button to the In or checked state.

Parameters

checked If TRUE the button is set to the checked state; if FALSE the button is unchecked.

virtual void SetCheckHighlight ( BOOL highlight )

pure virtual

Remarks: This method controls if the check button is displayed in the highlight color when pressed in.

Parameters

highlight TRUE if you want the button to use the highlight color; otherwise pass FALSE.

virtual void SetButtonDownNotify ( BOOL notify )

pure virtual

Remarks: Specifies if messages are sent when the user clicks or releases the button. If this method is called with TRUE, a message is sent immediately whenever the button is pressed down or released. The message BN_BUTTONDOWN is sent on button down and BN_BUTTONUP is sent when the button is released. The BN_BUTTONUP message is sent even if the button is released outside the button rectangle.

Parameters

notify TRUE if notification should be send by the button; FALSE if notifications should not be sent.

virtual void SetRightClickNotify ( BOOL notify )

pure virtual

Remarks: Specifies if messages are sent when the user right clicks the button.

Parameters

notify If TRUE, the BN_RIGHTCLICK message is sent whenever the users right clicks on the button. If FALSE no message are sent on right clicks.

virtual void SetHighlightColor ( COLORREF clr )

pure virtual

Remarks: This methods sets the highlight color for the check button.

Parameters

clr	The color for the button. It may be specified using the RGB macro, for example: SetHighlightColor(RGB(0,0,255));

virtual COLORREF GetHighlightColor ( )

pure virtual

Remarks: This methods returns the highlight color for the check button.

virtual void SetDADMgr ( DADMgr * dad )

pure virtual

Remarks: Sets the drag and drop manager for this button control.

Parameters

dad	A pointer to the drag and drop manager to set.

virtual DADMgr* GetDADMgr ( )

pure virtual

Remarks: Returns a pointer to the drag and drop manager for this button control.

virtual void SetMacroButtonData ( MacroButtonData * md )

pure virtual

Remarks: Sets the macro data for this button.

Parameters

md	The data to set. See Class MacroButtonData.

virtual MacroButtonData* GetMacroButtonData ( )

pure virtual

Remarks: Returns a pointer to any macro button data for this button. See Class MacroButtonData.

virtual MAX_DEPRECATED void SetDisplayProc ( PaintProc * proc )

inlinevirtual

2922 { };

virtual const MCHAR* GetCaptionText ( void )

pure virtual

virtual bool SetCaptionText ( const MCHAR * text )

pure virtual

virtual void UseIconAndText ( bool sw = true )

pure virtual

Remarks: If set to true, the button will be displayed with both an icon (if present) and text

ICustButton Class Reference

Class Description

Public Member Functions

Additional Inherited Members

Member Function Documentation