Class ISpinnerControl
See Also: Class ICustomControl, Custom Controls.
class ISpinnerControl : public ICustomControl
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.
Methods:
Prototype:
virtual float GetFVal()=0;
Remarks:
Returns the floating point value of the control.
Prototype:
virtual int GetIVal()=0;
Remarks:
This method returns the integer value of the control.
Prototype:
virtual void SetAutoScale(BOOL on=TRUE)=0;
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:
BOOL on=TRUE
If you wish to use auto scale pass TRUE to this method; otherwise FALSE.
Prototype:
virtual void SetScale(float s)=0;
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:
float s
The value is added to or subtracted from the current control value.
Prototype:
virtual void SetValue(float v, int notify)=0;
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:
float v
The new value for the control.
int 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.
Prototype:
virtual void SetValue(int v, int notify)=0;
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:
int v
The new value for the control.
int notify
If TRUE a message is sent indicating the control has changed.
Prototype:
virtual void SetLimits(int min, int max, int limitCurValue = TRUE)=0;
Remarks:
This method establishes the allowable limits for integer values entered.
Parameters:
int min
The minimum allowable value.
int max
The maximum allowable value.
int limitCurValue = TRUE
You may pass FALSE to the this parameter so the control will not send a spinner changed message when the limits are set.
Prototype:
virtual void SetLimits(float min, float max, int limitCurValue = TRUE)=0;
Remarks:
This method establishes the allowable limits for floating point values entered.
Parameters:
float min
The minimum allowable value.
float max
The maximum allowable value.
int limitCurValue = TRUE
You may pass FALSE to the this parameter so the control will not send a spinner changed message when the limits are set.
Prototype:
virtual void LinkToEdit(HWND hEdit, EditSpinnerType type)=0;
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:
HWND hEdit
The handle of the edit control to link.
EditSpinnerType 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).
Prototype:
virtual void SetIndeterminate(BOOL i=TRUE)=0;
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:
BOOL i=TRUE
Pass TRUE to this method to set the value to indeterminate.
Prototype:
virtual BOOL IsIndeterminate()=0;
Remarks:
This method returns TRUE if the current state of the spinner is indeterminate. See SetIndeterminate() above.
Prototype:
virtual void SetResetValue(float v)=0;
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:
float v
The reset value.
Prototype:
virtual void SetResetValue(int v)=0;
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:
int v
The reset value.
Prototype:
virtual void SetKeyBrackets(BOOL onOff)=0;
Remarks:
This method is available in release 2.0 and later only.
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:
BOOL 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.
Function:
void SetSpinnerPrecision(int p);
Remarks:
Sets the precision (number of decimal places displayed) used by the spinner control. Note that this function also affects slider controls. See Class ISliderControl.
Parameters:
int p
The number of decimal places to display in the edit box linked to the spinner control.
Function:
int GetSpinnerPrecision();
Remarks:
Returns the number of decimal places displayed in the edit box linked to a spinner control. Note that this function also affects slider controls. See Class ISliderControl.
Spinner controls have a global snap setting. This is set in 3ds max using File/Preferences... in the General page by changing the Spinner Snap setting. When enabled this specifies an increment that is applied to the current spinner value each time the UP or DOWN buttons are pressed on the spinner control.
Prototype:
void SetSnapSpinner(BOOL b);
Remarks:
This activates or de-activates the global spinner snap toggle.
Parameters:
BOOL b
TRUE to activate; FALSE to de-activate.
Prototype:
BOOL GetSnapSpinner();
Remarks:
Returns the global spinner snap setting; TRUE if on; FALSE if off.
Prototype:
void SetSnapSpinValue(float f);
Remarks:
This sets the global spinner snap increment or decrement value.
Parameters:
float f
The value that is added to or subtracted from the current spinner value when the arrow buttons are pressed.
Prototype:
float GetSnapSpinValue();
Remarks:
Returns the global spinner snap increment or decrement value.
Function:
ISpinnerControl *SetupFloatSpinner(HWND hwnd, int idSpin, int idEdit, float min, float max, float val, float scale = 0.1f);
Remarks:
This global function (not part of class ISpinnerControl) is used for setting up Spinners. It performs the equivalent of the GetISpinner(), SetLimits(), SetValue(), and LinkToEdit().
Parameters:
HWND hwnd
The handle of the dialog box in which the spinner appears.
int idSpin
The ID of the spinner.
int idEdit
The ID of the edit control.
float min
The minimum allowable value.
float max
The maximum allowable value.
float val
The initial value for the spinner.
float scale = 0.1f
The initial scale value for the spinner.
Return Value:
A pointer to the spinner control.
Sample Code:
Sample code to initialize a spinner / edit control.
to->custCtrlSpin = GetISpinner(GetDlgItem(hDlg, IDC_SPIN_SPINNER));
to->custCtrlSpin->SetLimits(0.0f, 100.0f, FALSE);
to->custCtrlSpin->SetValue(100.0f, FALSE);
to->custCtrlSpin->LinkToEdit(GetDlgItem(hDlg, IDC_SPIN_EDIT),
EDITTYPE_FLOAT);
The above code could be replaced with the following simplified code:
to->custCtrlSpin = SetupFloatSpinner(hDlg, IDC_SPIN_SPINNER,
IDC_SPIN_EDIT, 0.0f, 100.0f, 100.0f);
Function:
ISpinnerControl *SetupIntSpinner(HWND hwnd, int idSpin, int idEdit, int min, int max, int val);
Remarks:
This global function (not part of class ISpinnerControl) is used for setting up Spinners. It performs the equivalent of the GetISpinner(), SetLimits(), SetValue(), and LinkToEdit().
Parameters:
HWND hwnd
The handle of the dialog box in which the spinner appears.
int idSpin
The ID of the spinner.
int idEdit
The ID of the edit control.
int min
The minimum allowable value.
int max
The maximum allowable value.
int val
The initial value for the spinner.
Return Value:
A pointer to the spinner control.
Function:
void SetSpinDragNotify(BOOL onOff);
Remarks:
This global function is available in release 2.0 and later only.
This function controls whether or not spinners send CC_SPINNER_CHANGE notifications while the user adjusts them with the mouse.
Parameters:
BOOL onOff
TRUE to turn on; FALSE to turn off.
Function:
BOOL GetSpinDragNotify();
Remarks:
This global function is available in release 2.0 and later only.
Returns TRUE if CC_SPINNER_CHANGE notifications are sent by spinners while the user adjusts them with the mouse; FALSE if they are not sent.