Class ISliderControl

3DS Max Plug-In SDK

Class ISliderControl

See Also: Class ICustomControl, Class ISpinnerControl.

class ISliderControl : public ICustomControl

Description:

This class is available in release 3.0 and later only.

Important Note: The slider control ensures that it only displays, and the user is only allowed to input, values within the specified ranges. However the slider is just a front end to a controller which actually controls the value. The user can thus circumvent the slider 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.

 

image\slider1.gif (Slider Control)

image\slider2.gif ('Bracketed' Slider Control)

The custom slider control is functionality similar to the custom spinner control. It supports the following features:

- can link to custom edit box. 

- right click reset of value. 

if not dragging, resets to default reset value. 

if dragging, resets to previous value. 

- shift+right click sets an animation key. 

- red highlight for animated key positions. 

It also supports the following functionality:

- dynamically set tick marks segment the slider track. 

- default reset value and last value are visually indicated. 

- left click in slider track moves button to that position. 

- ctrl key snaps to nearest tick mark. 

Also Note: Developers should use the functions Get/SetSpinnerPrecision() for controlling precision of edit boxes linked to slider controls. Those functions affect both spinners and sliders.

To initialize the pointer to the control call:

Function:

ISliderControl *GetISlider(HWND hCtrl);

To release the control call:

Function:

void ReleaseISlider(ISliderControl *isc);

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

The following messages may be sent by the slider control:

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

CC_SLIDER_CHANGE

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

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

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

This message is sent when the user presses down on the slider.

CC_SLIDER_BUTTONDOWN

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

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

This message is sent when the user releases a slider.

CC_SLIDER_BUTTONUP

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

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

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

Methods:

public:

Prototype:

virtual float GetFVal()=0;

Remarks:

Returns the floating point value of the control.

Prototype:

virtual int GetIVal()=0;

Remarks:

Returns the integer value of the control.

Prototype:

virtual void SetNumSegs(int num)=0;

Remarks:

Sets the number of segments (tick marks) used by the control.

Parameters:

int num

The number to set.

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; if FALSE no message is sent.

Prototype:

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

Remarks:

This method sets the value of the control to the specific integer number passed. You may pass FALSE as the notify parameter so the control wont 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; if FALSE no message is sent.

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 slider control, this method is used to link the two, so values entered using the slider 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 slider, the value is indeterminate. When TRUE, the value field of the slider 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 slider is indeterminate; otherwise FALSE. See SetIndeterminate() above.

Prototype:

virtual void SetResetValue(float v)=0;

Remarks:

A user may right click on a slider to reset it to its 'reset' value (after it has 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 user may right click on a slider to reset it to its 'reset' value (after it has 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:

Sets the display of the 'brackets' surrounding the slider control. This is used to indicate if a key exists for the parameter controlled by the slider 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. For a slider, the 'brackets' appear as a colored dot in the position marker.

Parameters:

BOOL onOff

TRUE for on; FALSE for off.

The following functions are not members of this class but are available for use:

Function:

ISliderControl *SetupIntSlider(HWND hwnd, int idSlider, int idEdit, int min, int max, int val, int numSegs);

Remarks:

This global function is used for setting up integer sliders. It performs the equivalent of the GetISlider(), SetLimits(), SetValue(), and LinkToEdit().

Parameters:

HWND hwnd

The handle of the dialog box in which the slider appears.

int idSlider

The ID of the slider.

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.

int numSegs

The number of segments to use for the control.

Return Value:

A pointer to the slider control.

Function:

ISliderControl *SetupFloatSlider(HWND hwnd, int idSlider, int idEdit, float min, float max, float val, int numSegs);

Remarks:

This global function is used for setting up floating point sliders. It performs the equivalent of the GetISlider(), SetLimits(), SetValue(), and LinkToEdit().

Parameters:

HWND hwnd

The handle of the dialog box in which the slider appears.

int idSlider

The ID of the slider.

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.

int numSegs

The number of segments to use for the control.

Return Value:

A pointer to the slider control.

Function:

ISliderControl *SetupUniverseSlider(HWND hwnd, int idSlider, int idEdit, float min, float max, float val, int numSegs);

Remarks:

This global function is used for setting up 'universal' value sliders (EDITTYPE_UNIVERSE -- these display world space units). It performs the equivalent of the GetISlider(), SetLimits(), SetValue(), and LinkToEdit().

Parameters:

HWND hwnd

The handle of the dialog box in which the slider appears.

int idSlider

The ID of the slider.

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.

int numSegs

The number of segments to use for the control.

Return Value:

A pointer to the slider control.

Function:

void SetSliderDragNotify(BOOL onOff);

Remarks:

This function controls whether or not sliders send CC_SLIDER_CHANGE notifications while the user adjusts them with the mouse.

Parameters:

BOOL onOff

TRUE to turn on; FALSE to turn off.

Function:

BOOL GetSliderDragNotify();

Remarks:

Returns TRUE if CC_SLIDER_CHANGE notifications are sent by sliders while the user adjusts them with the mouse; FALSE if they are not sent.