This reference page is linked to from the following overview topics: Processing User Input from Custom Controls, Methods and Classes of Custom Controls.

Detailed Description

See also:: Class ICustomControl, Custom 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.

#include <custcont.h>

Inheritance diagram for ISpinnerControl:

[legend]

List of all members.

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

Member Function Documentation

virtual float GetFVal ( ) [pure virtual]

Search for all occurrences

Remarks:: Returns the floating point value of the control.

virtual int GetIVal ( ) [pure virtual]

Search for all occurrences

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

virtual void SetAutoScale ( BOOL on = TRUE ) [pure virtual]

Search for all occurrences

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]

Search for all occurrences

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]`

Search for all occurrences

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]`

Search for all occurrences

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]`

Search for all occurrences

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]`

Search for all occurrences

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]`

Search for all occurrences

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]

Search for all occurrences

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]

Search for all occurrences

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

virtual void SetResetValue ( float v ) [pure virtual]

Search for all occurrences

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]

Search for all occurrences

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]

Search for all occurrences

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

Detailed Description

Public Member Functions

Member Function Documentation