#include <custcont.h>

Class Description

See also: Class ICustomControl, Custom User Interface Controls.

Description:: The spinner control is used (usually in conjunction with the custom edit control) to provide input of values limited to a fixed type. For example, the control may be limited to the input of only positive integers. The input options are integer, float, universe (world space coordinates), positive integer, positive float, positive universal, and time. This control allows the user to increment or decrement a value by clicking on the up or down arrows. The user may also click and drag on the arrows to interactively adjust the value. The Ctrl key may be held to accelerate the value changing speed, while the Alt key may be held to decrease the value changing speed.

The standard size used by 3ds Max for the spinner control is 7 wide by 10 high. If you use a larger size, the spinner control arrows will be position in the upper left corner of the control.

Important Note: The spinner control ensures that it only displays, and the user is only allowed to input, values within the specified ranges. However the spinner is just a front end to a controller which actually controls the value. The user can thus circumvent the spinner constraints by editing the controller directly (via function curves in track view, key info, etc.). Therefore, when a plug-in gets a value from a controller (or a parameter block, which may use a controller) it is its responsibility to clamp the value to a valid range.

Spinner Control

Spinner and Edit Control
To initialize the pointer to the control call:

ISpinnerControl *GetISpinner(HWND hCtrl);

To release the control call:

ReleaseISpinner(ISpinnerControl *isc);

The value to use in the Class field of the Custom Control Properties dialog is: SpinnerControl

The following messages may be sent by the spinner control:

This message is sent when the value of a spinner changes.

CC_SPINNER_CHANGE

lParam contains a pointer to the spinner control. You can cast this pointer to a ISpinnerControl type and then call methods of the control.

LOWORD(wParam) contains the ID of the spinner. This is the named established in the ID field of the Custom Control Properties dialog.

HIWORD(wParam) is TRUE if the user is dragging the spinner interactively.

This message is sent when the user presses down on the spinner buttons.

CC_SPINNER_BUTTONDOWN

lParam contains a pointer to the spinner control. You can cast this pointer to a ISpinnerControl type and then call methods of the control.

LOWORD(wParam) contains the ID of the spinner. This is the named established in the ID field of the Custom Control Properties dialog.

This message is sent when the user releases a spinner button.

CC_SPINNER_BUTTONUP

lParam contains a pointer to the spinner control. You can cast this pointer to a ISpinnerControl type and then call methods of the control.

LOWORD(wParam) contains the ID of the spinner. This is the named established in the ID field of the Custom Control Properties dialog.

HIWORD(wParam) is FALSE if the user canceled and TRUE otherwise.

For example, if the user is interactively dragging the spinner, then does a right click to cancel, the following messages are sent:

1 A CC_SPINNER_BUTTONDOWN message indicating the user has pressed the spinner button.

2. A series of CC_SPINNER_CHANGE where HIWORD(wParam) = TRUE. This indicates that the spinner is being dragged interactively.

3. A CC_SPINNER_CHANGE where HIWORD(wParam) = FALSE.

4. A CC_SPINNER_BUTTONUP message where HIWORD(wParam) = FALSE. This indicates the user has cancelled.

Inheritance diagram for ISpinnerControl:

Public Member Functions
virtual float	GetFVal ()=0

virtual int	GetIVal ()=0

virtual void	SetAutoScale (BOOL on=TRUE)=0

virtual void	SetScale (float s)=0

virtual void	SetValue (float v, int notify)=0

virtual void	SetValue (int v, int notify)=0

virtual void	SetLimits (int min, int max, int limitCurValue=TRUE)=0

virtual void	SetLimits (float min, float max, int limitCurValue=TRUE)=0

virtual void	LinkToEdit (HWND hEdit, EditSpinnerType type)=0

virtual void	SetIndeterminate (BOOL i=TRUE)=0

virtual BOOL	IsIndeterminate ()=0

virtual void	SetResetValue (float v)=0

virtual void	SetResetValue (int v)=0

virtual void	SetKeyBrackets (BOOL onOff)=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...

Member Function Documentation

virtual float GetFVal ( )

pure virtual

Remarks: Returns the floating point value of the control.

virtual int GetIVal ( )

pure virtual

Remarks: This method returns the integer value of the control.

virtual void SetAutoScale ( BOOL on = TRUE )

pure virtual

Remarks: This method sets the scale for the spinner based on the current value of the spinner. This allows the spinner to cover a larger range of values with less mouse motion. If you wish to use auto scale, pass TRUE to this method.

Parameters

on	If you wish to use auto scale pass TRUE to this method; otherwise FALSE.

virtual void SetScale ( float s )

pure virtual

Remarks: This method sets the value which is added to or subtracted from the current control value as the arrow buttons are pressed, or the user interactively drags the spinner.

Parameters

s	The value is added to or subtracted from the current control value.

virtual void SetValue	(	float	v,
		int	notify
	)

pure virtual

Remarks: This method sets the value of the control to the specific floating point number passed. You may pass FALSE as the notify parameter so the control wont send a message when you set the value.

Parameters

v The new value for the control.

notify If TRUE a message is sent indicating the control has changed.

Note that sometimes the SetValue() method is used to update the display of parameters in the user interface. For example, if the user changes the current time and the UI parameters are animated, the user interface controls must be updated to reflect the value at the new time. The programmer calls SetValue() to update the value displayed in the control. This is an example of when to pass FALSE as the notify parameter. If you were to pass TRUE, a message would be sent as if the user had actually enter a new value at this time. These are of course very different conditions.

virtual void SetValue	(	int	v,
		int	notify
	)

pure virtual

Remarks: This method sets the value to the specific integer passed. You may pass FALSE as the notify parameter so the control won't send a message when you set the value.

Parameters

v	The new value for the control.
notify	If TRUE a message is sent indicating the control has changed.

virtual void SetLimits	(	int	min,
		int	max,
		int	limitCurValue = `TRUE`
	)

pure virtual

Remarks: This method establishes the allowable limits for integer values entered.

Parameters

min	The minimum allowable value.
max	The maximum allowable value.
limitCurValue	You may pass FALSE to the this parameter so the control will not send a spinner changed message when the limits are set.

virtual void SetLimits	(	float	min,
		float	max,
		int	limitCurValue = `TRUE`
	)

pure virtual

Remarks: This method establishes the allowable limits for floating point values entered.

Parameters

min	The minimum allowable value.
max	The maximum allowable value.
limitCurValue	You may pass FALSE to the this parameter so the control will not send a spinner changed message when the limits are set.

virtual void LinkToEdit	(	HWND	hEdit,
		EditSpinnerType	type
	)

pure virtual

Remarks: When an edit control is used in conjunction with the spinner control, this method is used to link the two, so values entered using the spinner are displayed in the edit control. This method is also used to set the type of value which may be entered.

Parameters

hEdit The handle of the edit control to link.

type The type of value that may be entered. One of the following values:

EDITTYPE_INT
Any integer value.

EDITTYPE_FLOAT
Any floating point value.

EDITTYPE_UNIVERSE
This is a value in world space units. It respects the system's unit settings (for example feet and inches).

EDITTYPE_POS_INT
Any integer >= 0

EDITTYPE_POS_FLOAT
\ Any floating point value >= 0.0

EDITTYPE_POS_UNIVERSE
This is a positive value in world space units. It respects the system's unit settings (for example feet and inches).

EDITTYPE_TIME
This is a time value. It respects the system time settings (SMPTE for example).

virtual void SetIndeterminate ( BOOL i = TRUE )

pure virtual

Remarks: This method is used to show commonality. When several different values are being reflected by the spinner, the value is indeterminate. When TRUE, the value field of the spinner appears empty.

Parameters

i	Pass TRUE to this method to set the value to indeterminate.

virtual BOOL IsIndeterminate ( )

pure virtual

Remarks: This method returns TRUE if the current state of the spinner is indeterminate. See SetIndeterminate() above.

virtual void SetResetValue ( float v )

pure virtual

Remarks: A 3ds Max user may right click on the spinner buttons to reset them to their 'reset' value (after they have been changed). This method specifies the value used when the reset occurs.

Parameters

v	The reset value.

virtual void SetResetValue ( int v )

pure virtual

Remarks: A 3ds Max user may right click on the spinner buttons to reset them to their 'reset' value (after they have been changed). This method specifies the value used when the reset occurs.

Parameters

v	The reset value.

virtual void SetKeyBrackets ( BOOL onOff )

pure virtual

Remarks: Sets the display of the brackets surrounding the spinner control to on. This is used to indicate if a key exists for the parameter controlled by the spinner at the current time. These brackets turned on and off automatically if you are using a parameter map and parameter block to handle the control. If not you'll need to use this method.

Parameters

onOff TRUE for on; FALSE for off.

Sample Code:: This example shows how you do this if you only use a parameter block.

case CC_SPINNER_CHANGE:

switch (LOWORD(wParam))

{

case IDC_LENSPINNER:

th->SetLength(th->ip->GetTime(),th->lengthSpin->GetFVal());

th->lengthSpin->SetKeyBrackets(th->pblock->

KeyFrameAtTime(PB_LENGTH,th->ip->GetTime()));

break;

}

return TRUE;

The following functions are not part of class ISpinnerControl but are available for use with spinner controls.

ISpinnerControl Class Reference

Class Description

Public Member Functions

Additional Inherited Members

Member Function Documentation