IBaseGrip Class Reference

This reference page is linked to from the following overview topics: Major New Features, SDK Change Details, Caddy Controls.

---

Search for all occurrences

---

Detailed Description

A pure virtual interface for implementing grips.

class IBaseGrip A Grip or Caddy is a collection of modeless, transparent, in canvas UI elements that lets a user perform actions or modify values. A user can create their own grip by inheriting from IBaseGrip, implementing IBaseGrip's pure virtual functions, and then enable it on via the IGripManager interface. Based upon the number of grip items the grip contains and the type each item is, the system will create a set of in canvas UI representations for each item, which then interact with the IBaseGrip item via various functions. Usually the implementation of the IBaseGrip acts as a bridge between some existing data and the in canvas UI. For example if a grip was created to modify different soft selection values in a modifier, the grip would get the values from that modifier and then set the values back onto it. The grip itself will get displayed via the IGripManager::EnableGrip function which basically calls various IBaseGrip functions to set up the in canvas UI and then ferry messages to and from the UI to the grip.

See also:

IGripManager. There are a collection of implemented grips present in the sdk at maxsdk\samples\mesh\editablepoly\polygrips.h, polygrips.cpp

#include <igrip.h>

Inheritance diagram for IBaseGrip:

List of all members.

Classes
struct	ComboLabel
	The label and icon that make up each individual option for Type::eCombo grip item. More...
struct	GripValue
	The grip value that's used by the grip item when it's value is retrieved via GetValue or set via SetValue. More...
Public Types
enum	Type {   eInvalid = -1, eInt = 0, eFloat, eTime,   eUniverse, eCombo, eToggle, eAction,   eCommand, eStatus }
enum	Customization { eSameRow = 0x1, eTurnOffLabel = 0x2, eDisableAlt = 0x4 }
Public Member Functions
virtual	~IBaseGrip ()
	Deconstructor.
virtual void	GetGripName (MSTR &string)=0
	Get the name of the grip.
virtual int	GetNumGripItems ()=0
	Get the number of grip items this grip contains.
virtual IBaseGrip::Type	GetType (int which)=0
	Get the type that the specified grip item will control.
virtual bool	GetText (int which, MSTR &string)=0
	Get the name of the specified grip item.
virtual bool	GetResolvedIconName (int which, MSTR &string)=0
	Get the file path of the icon that represents the specified grip item.
virtual DWORD	GetCustomization (int which)=0
	Get any special customization flags that this grip item needs to follow.
virtual bool	GetComboOptions (int which, Tab< ComboLabel * > &comboOptions)=0
	Get the option possibilities for this combo grip item.
virtual bool	GetCommandIcon (int which, MSTR &string)=0
	Get an icon for the IBaseGrip::eCommand grip item.
virtual bool	GetValue (int which, TimeValue t, IBaseGrip::GripValue &value)=0
	Get the value of the specified grip item.
virtual bool	ShowKeyBrackets (int which, TimeValue t)=0
	Whether or not key brackets, which will show in a spinner that a key is present, should be shown at the specified time.
virtual bool	GetRange (int which, IBaseGrip::GripValue &minRange, IBaseGrip::GripValue &maxRange)=0
	Get the range of this grip values.
virtual bool	GetResetValue (int which, IBaseGrip::GripValue &resetValue)=0
	Get the reset value of the grip.
virtual bool	ResetValue (TimeValue t, int which)=0
	Reset the specified grip.
Operations
The Okay, Cancel and Apply operations that a grip may implement.
virtual bool	SupportsOkayApplyCancel ()=0
	Whether or not, the Okay, Apply and Cancel grip buttons will get shown or not.
virtual void	Okay (TimeValue t)=0
	Accept any necessary changes and disable the grip to close the UI.
virtual void	Cancel ()=0
	Disregard and cancel any necessary changes and disable the grip to close the UI.
virtual void	Apply (TimeValue t)=0
	Accept any necessary changes and perform any pending action if needed.
Set Functions
Set of functions which are called when setting a value. Note that SetValue may be called multiple times within each StartSetValue pair.
virtual bool	SetValue (int which, TimeValue t, IBaseGrip::GripValue &value)=0
	Set the value of the specified.
virtual bool	StartSetValue (int which, TimeValue t)=0
	Get ready to set this value.
virtual bool	EndSetValue (int which, TimeValue t, bool accepted)=0
	The value is done setting values.
Scaling Functions
Set of functions which are called when the grip is scaled by either incrementing or decrementing it. This value is the value that will thus added or subtracted from it. Only supports those grip items which have spinners.
virtual bool	GetAutoScale (int which)=0
	Whether or nor we will use auto scaling when incrementing or decrementing this item.
virtual bool	GetScale (int which, IBaseGrip::GripValue &scaleValue)=0
	Get the scale value for this item when we increment or decrement it.
virtual bool	GetScaleInViewSpace (int which, float &depth)=0
	Get the scale value for this grip in view space, if one exists.

---

Constructor & Destructor Documentation

virtual ~IBaseGrip

(

)

[inline, virtual]

Deconstructor.

{};

---

Member Function Documentation

virtual bool SupportsOkayApplyCancel

(

)

[pure virtual]

Search for all occurrences

Whether or not, the Okay, Apply and Cancel grip buttons will get shown or not.

Returns:

If true the grip will have Okay, Apply and grip buttons that will then trigger the correct callback functions listed below. If false, then the grip won't show these buttons.

virtual void Okay

(

TimeValue

t

)

[pure virtual]

Search for all occurrences

Accept any necessary changes and disable the grip to close the UI.

Basically do whatever operations you would do similar if the Okay button was pressed in a modeless dialog. Note that it's the implementations responsibility to disable the grip.

Parameters:

[in]

t

The time at which to perform the okay.

virtual void Cancel

(

)

[pure virtual]

Search for all occurrences

Disregard and cancel any necessary changes and disable the grip to close the UI.

Basically do whatever operations you would do similar if the Cancel button was pressed in a modeless dialog. Note that it's the implementations responsibility to disable the grip.

virtual void Apply

(

TimeValue

t

)

[pure virtual]

Search for all occurrences

Accept any necessary changes and perform any pending action if needed.

Unlike Okay, after an Apply the grip stays active and displayed.

Parameters:

[in]

t

The time at which to perform the apply.

virtual void GetGripName

(

MSTR &

string

)

[pure virtual]

Search for all occurrences

Get the name of the grip.

Parameters:

[out]

string

The name of the grip.

virtual int GetNumGripItems

(

)

[pure virtual]

Search for all occurrences

Get the number of grip items this grip contains.

Returns:

The number of grip items this grip contains.

virtual IBaseGrip::Type GetType

(

int

which

)

[pure virtual]

Search for all occurrences

Get the type that the specified grip item will control.

Parameters:

[in]

which

The zero based index of the item.

Returns:

The type of the specified grip item.

See also:

IBaseGrip::Type to see the different types that a grip item may be. The type that the grip item is determines what IBaseGrip::Value values the grip item supports. If the index is out of range then return Type::eInvalid.

virtual bool GetText	(	int	which,
		MSTR &	string
	)		[pure virtual]

Search for all occurrences

Get the name of the specified grip item.

Parameters:

[in]	which	The zero based index of the item.
[out]	string	The name of the specified grip item.

Returns:

true if the operation succeeded, false otherwise.

virtual bool GetResolvedIconName	(	int	which,
		MSTR &	string
	)		[pure virtual]

Search for all occurrences

Get the file path of the icon that represents the specified grip item.

Every grip item no matter it's type should try to provide an icon that represents the string that's returned by GetText.

Parameters:

[in]	which	The zero based index of the grip item.
[out]	string	The name of the resolved path of the icon. It's this functions responsibility to resolve the path completely.

Returns:

true if the operation succeeded, false otherwise.

virtual DWORD GetCustomization

(

int

which

)

[pure virtual]

Search for all occurrences

Get any special customization flags that this grip item needs to follow.

See also:

IBaseGrip::Customization.

Parameters:

[in]

which

The zero based index of the item.

Returns:

Returns a bitwise union of IBaseGrip::Customization types, casted to a DWORD, that specify what if any customizations this grip item will have that differ from the default behavior of that grip item. Note that this customization is only checked when the grip is activated and its UI is constructed. Return zero if index is invalid or no customization occurs.

virtual bool GetComboOptions	(	int	which,
		Tab< ComboLabel * > &	comboOptions
	)		[pure virtual]

Search for all occurrences

Get the option possibilities for this combo grip item.

Parameters:

[in]	which	The zero based index of the item.
[out]	cobmoOptions	A returned tab of labels that describes each possible option for the IBaseGrip::eCombo type grip button. These values will be presented in the UI as the possible options which can be selected. Note that it's the responsiblity of the client of this function to delete each allocated ComboLabel pointer in the Tab.

Returns:

Returns true if the options were correctly set up, false if not, for example if this grip item isn't a eCombo type.

virtual bool GetCommandIcon	(	int	which,
		MSTR &	string
	)		[pure virtual]

Search for all occurrences

Get an icon for the IBaseGrip::eCommand grip item.

Since a IBaseGrip::eCommand can have two different states, the grip item can show additional icons, in addition to the one returned by GetResolvedIconName, to represent these states.

Parameters:

[in]	which	The zero based index of the grip item.
[out]	string	The name of the resolved path of the icon. It's this functions responsibility to resolve the path completely.

Returns:

Returns true if an icon was resolved up, false if not, for example if this grip item isn't a IBaseGrip::eCommmand type.

virtual bool GetValue	(	int	which,
		TimeValue	t,
		IBaseGrip::GripValue &	value
	)		[pure virtual]

Search for all occurrences

Get the value of the specified grip item.

Parameters:

[in]	which	The zero based index of the grip item.
[in]	t	The time at which to get the value.
[out]	value	The value for that grip. See ::GripValue to see the values that are supported.

Returns:

true if the operation succeeded, false otherwise.

virtual bool SetValue	(	int	which,
		TimeValue	t,
		IBaseGrip::GripValue &	value
	)		[pure virtual]

Search for all occurrences

Set the value of the specified.

Parameters:

[in]	which	The zero based index of the grip item.
[in]	t	The time at which to set the value.
[in]	value	The value for that grip. See ::GripValue to see the values that are supported.

Returns:

true if the operation succeeded, false otherwise.

virtual bool StartSetValue	(	int	which,
		TimeValue	t
	)		[pure virtual]

Search for all occurrences

Get ready to set this value.

Sometimes an item needs to do some setup before a value get's set, for example cache some values, or get ready for an undo. This is called before SetValue is called and SetValue may be called multiple times after StartSetValue is called.

Parameters:

[in]	which	The zero based index of the grip item.
[in]	t	The time at which to set the value.

Returns:

true if the operation succeeded, false otherwise.

virtual bool EndSetValue	(	int	which,
		TimeValue	t,
		bool	accepted
	)		[pure virtual]

Search for all occurrences

The value is done setting values.

Sometimes an item needs to do some cleanup after a value get's set, for example delete some cached values or accept an undo. This will get called immediately after the last SetValue function get's called.

Parameters:

[in]	which	The zero based index of the grip item.
[in]	t	The time at which the value was set.
[in]	accepted	If true the setvalue operation has succeeded and any undo's may be accepted if needed. If false then the setvalue operation was canceled and it's the implementors responsibility to rever the value back to it's original value it had when StartSetValue was called, for example it could do this by canceling the hold.

Returns:

true if the operation succeeded, false otherwise.

virtual bool ShowKeyBrackets	(	int	which,
		TimeValue	t
	)		[pure virtual]

Search for all occurrences

Whether or not key brackets, which will show in a spinner that a key is present, should be shown at the specified time.

Usually this function will check to see if a key exists at this time.

Parameters:

[in]	which	The zero based index of the grip item, which we are checking key brackets for. Will only check for those grip items which have spinners.
[in]	t	The time at which we are checking to see if we should show a key bracket.

Returns:

true if a key bracket should be shown at that time, false otherwise.

virtual bool GetAutoScale

(

int

which

)

[pure virtual]

Search for all occurrences

Whether or nor we will use auto scaling when incrementing or decrementing this item.

Parameters:

[in]

which

The zero based index of the grip item.

Returns:

Returns true if the grip should auto scale this value, false if not.

virtual bool GetScale	(	int	which,
		IBaseGrip::GripValue &	scaleValue
	)		[pure virtual]

Search for all occurrences

Get the scale value for this item when we increment or decrement it.

Will normally only get used if GetAutoScale and GetSCaleInViewSpace returns false.

Parameters:

[in]	which	The zero based index of the grip item.
[out]	scaleValue	The value of the scale.

Returns:

true if the operation succeeded, false otherwise.

virtual bool GetScaleInViewSpace	(	int	which,
		float &	depth
	)		[pure virtual]

Search for all occurrences

Get the scale value for this grip in view space, if one exists.

Parameters:

[in]	which	The zero based index of the grip item.
[out]	depth	The screen space depth that the scale should use. /see ViewExp::MapScreenToView for a more in depth description on screen depth. -200 is usually a good default value.

Returns:

Returns true if we should support scaling in view space, false if not. If false then we either using auto scaling or the normal incremental scale value specified by GetScale, based upon the result of GetAutoScale. Screen space scaling is used when dragging on a grip item spinner.

virtual bool GetRange	(	int	which,
		IBaseGrip::GripValue &	minRange,
		IBaseGrip::GripValue &	maxRange
	)		[pure virtual]

Search for all occurrences

Get the range of this grip values.

Parameters:

[in]	which	The grip item
[in]	minRange	The minimum range value for this grip. If the grip type is Type::eAction then no valid value is expected.
[in]	maxRange	The maximum range value for this grip. If the grip type is Type::eAction then no valid value is expected.

Returns:

true if the operation succeeded, false otherwise.

virtual bool GetResetValue	(	int	which,
		IBaseGrip::GripValue &	resetValue
	)		[pure virtual]

Search for all occurrences

Get the reset value of the grip.

Parameters:

[in]	which	The grip item whose reset value we will get.
[out]	resetValue	The resetValue for that value. If the grip type is eAction then no valid value is expected.

Returns:

true if the operation succeeded, false otherwise.

virtual bool ResetValue	(	TimeValue	t,
		int	which
	)		[pure virtual]

Search for all occurrences

Reset the specified grip.

Parameters:

[in]	t	The time at which to reset.
[in]	which	Which grip item to reset.

Returns:

true if the operation succeeded, false otherwise.