#include <iparamb2.h>

Class Description

See also: Class ClassDesc2, Class ParamMap2UserDlgProc, Class Mtl, Class Texmap, Class PBBitmap, Class PBAccessor, Class INode, Class Color, Class Point3, Class ReferenceTarget, Structure ParamDef,
ParamType, ParamType2,
List of ParamTags Choices

Description:: In the Parameter Block2 scheme there is one ParamBlockDesc2 object per entire Parameter Block2.

This class is used when adding a paramblock descriptor for each parameter block2. This is usually done in the form of a static instance of this class. The constructor takes a number of fixed, block-related arguments and then a varargs-based variable list of arguments that define the block and its parameters.

All methods of this class are implemented by the System.

Data Members:: ParamDef* paramdefs;

Array of parameter definitions.

ClassDesc2* cd;

This is the class descriptor of the class which owns this parameter block descriptor.

MCHAR* int_name;

This is the internal name of this parameter descriptor. This name is not localized. Internal names are meant to be parsable as identifiers. As such they should begin with an alpha character, have only alphanumerics, and have no spaces, punctuations, etc. The convention for multi-word names is to use studly-caps, eg, paintRadius.

int local_name;

This is the string table resource ID for the localized (sub-anim) name.

BlockID ID;

The permanent parameter block ID.

USHORT count;

The number of parameters in block.

ULONG version;

This is the parameter block version.

BYTE flags;

One or more of the following 11 values (see the constructor argument flags below for details): P_CLASS_PARAMS P_AUTO_CONSTRUCT P_AUTO_UI P_AUTO_UI_QT P_USE_PARAMS P_INCLUDE_PARAMS P_SCRIPTED_CLASS P_TEMPORARY P_HASCATEGORY P_CALLSETS_ON_LOAD P_TEMPLATE_UI P_VERSION (New in Max8) Note: The following data members are optional and used by the auto-construct code:

int ref_no;

The reference number for the auto-constructed parameter block.

int dlg_template;

The rollout dialog template resource.

int title;

String table resource ID of the rollout title.

int test_flags;

The ClassDesc2::Begin/EndEditParams() test flags. See the flag_mask parameter description below for details.

int rollup_flags;

This is used to control rollup creation. See the rollup_flags parameter description below for details.

ParamMap2UserDlgProc* dlgProc;

Points to the parameter map user dialog proc (if used).

MSPluginClass* pc;

If this ParamBlockDesc2 belongs to a scripted plug-in this points to the scripted class (or NULL otherwise). SeeMAXScript SDK.

Value* rollout;

If this ParamBlockDesc2 belongs to a scripted plug-in this points to rollout name. See MAXScript SDK.

IParamBlock2* class_params;

Pointer to class parameter block if the CLASS_PARAM flag is specified for the block. See the flags descriptions below for details.

Inheritance diagram for ParamBlockDesc2:

Classes
struct	map_spec

Public Member Functions
	ParamBlockDesc2 ()

PB2Export	ParamBlockDesc2 (BlockID ID, const MCHAR int_name, StringResID local_name, ClassDesc2 cd, USHORT flags,...)

PB2Export	~ParamBlockDesc2 ()

PB2Export void	AddParam (ParamID id,...)

PB2Export void	ReplaceParam (ParamID id,...)

void	DeleteParam (ParamID id)

PB2Export void	DeleteParamByIndex (int index)

PB2Export void	DeleteAllParams ()

PB2Export void	ParamOption (ParamID id, int option_tag,...)

PB2Export bool	ParamOptionEnableCtrls (ParamID pID, const Tab< ParamID > &dependentPIDs)
	Modifies the list of controls enabled by a certain control This method allows to modify the list of controls that are enabled/disabled by a given control that represents a boolean parameter. More...

PB2Export bool	ParamOptionContentValues (ParamID id, Tab< int > &stringItems, Tab< int > *stringItemValues=NULL)
	This method is used for modifying a descriptor incrementally. More...

PB2Export void	SetClassDesc (ClassDesc2 *pCD)

USHORT	Count ()

DWORD	Version ()

PB2Export int	IDtoIndex (ParamID id)

PB2Export int	NameToIndex (const MCHAR *name)
	Finds the parameter with the matching internal name (ParamDef::int_name), and returns its index. More...

ParamID	IndextoID (int i)

ParamDef &	GetParamDef (ParamID id)

const ParamDef *	GetParamDefByIndex (const unsigned int parameterIndex) const
	Returns the parameter definition for the parameter with the given index. More...

BOOL	SetValue (ParamID id, TimeValue t, float v, int tabIndex=0)

BOOL	SetValue (ParamID id, TimeValue t, int v, int tabIndex=0)

BOOL	SetValue (ParamID id, TimeValue t, Point2 &v, int tabIndex=0)

BOOL	SetValue (ParamID id, TimeValue t, Point3 &v, int tabIndex=0)

BOOL	SetValue (ParamID id, TimeValue t, Point4 &v, int tabIndex=0)

BOOL	SetValue (ParamID id, TimeValue t, Color &v, int tabIndex=0)

BOOL	SetValue (ParamID id, TimeValue t, AColor &v, int tabIndex=0)

BOOL	SetValue (ParamID id, TimeValue t, const MCHAR *v, int tabIndex=0)

BOOL	SetValue (ParamID id, TimeValue t, Mtl *v, int tabIndex=0)

BOOL	SetValue (ParamID id, TimeValue t, Texmap *v, int tabIndex=0)

BOOL	SetValue (ParamID id, TimeValue t, PBBitmap *v, int tabIndex=0)

BOOL	SetValue (ParamID id, TimeValue t, INode *v, int tabIndex=0)

BOOL	SetValue (ParamID id, TimeValue t, ReferenceTarget *v, int tabIndex=0)

BOOL	SetValue (ParamID id, TimeValue t, IParamBlock2 *v, int tabIndex=0)

BOOL	SetValue (ParamID id, TimeValue t, Matrix3 &v, int tabIndex=0)

BOOL	GetValue (ParamID id, TimeValue t, float &v, Interval &ivalid, int tabIndex=0)

BOOL	GetValue (ParamID id, TimeValue t, int &v, Interval &ivalid, int tabIndex=0)

BOOL	GetValue (ParamID id, TimeValue t, Point2 &v, Interval &ivalid, int tabIndex=0)

BOOL	GetValue (ParamID id, TimeValue t, Point3 &v, Interval &ivalid, int tabIndex=0)

BOOL	GetValue (ParamID id, TimeValue t, Point4 &v, Interval &ivalid, int tabIndex=0)

BOOL	GetValue (ParamID id, TimeValue t, Color &v, Interval &ivalid, int tabIndex=0)

BOOL	GetValue (ParamID id, TimeValue t, AColor &v, Interval &ivalid, int tabIndex=0)

BOOL	GetValue (ParamID id, TimeValue t, const MCHAR *&v, Interval &ivalid, int tabIndex=0)

BOOL	GetValue (ParamID id, TimeValue t, Mtl *&v, Interval &ivalid, int tabIndex=0)

BOOL	GetValue (ParamID id, TimeValue t, Texmap *&v, Interval &ivalid, int tabIndex=0)

BOOL	GetValue (ParamID id, TimeValue t, PBBitmap *&v, Interval &ivalid, int tabIndex=0)

BOOL	GetValue (ParamID id, TimeValue t, INode *&v, Interval &ivalid, int tabIndex=0)

BOOL	GetValue (ParamID id, TimeValue t, ReferenceTarget *&v, Interval &ivalid, int tabIndex=0)

BOOL	GetValue (ParamID id, TimeValue t, IParamBlock2 *&v, Interval &ivalid, int tabIndex=0)

BOOL	GetValue (ParamID id, TimeValue t, Matrix3 &v, Interval &ivalid, int tabIndex=0)

PB2Export Color	GetColor (ParamID id, TimeValue t=0, int tabIndex=0)

PB2Export AColor	GetAColor (ParamID id, TimeValue t=0, int tabIndex=0)

PB2Export Point2	GetPoint2 (ParamID id, TimeValue t=0, int tabIndex=0)

PB2Export Point3	GetPoint3 (ParamID id, TimeValue t=0, int tabIndex=0)

PB2Export Point4	GetPoint4 (ParamID id, TimeValue t=0, int tabIndex=0)

PB2Export int	GetInt (ParamID id, TimeValue t=0, int tabIndex=0)

PB2Export float	GetFloat (ParamID id, TimeValue t=0, int tabIndex=0)

PB2Export TimeValue	GetTimeValue (ParamID id, TimeValue t=0, int tabIndex=0)

PB2Export const MCHAR *	GetStr (ParamID id, TimeValue t=0, int tabIndex=0)

PB2Export Mtl *	GetMtl (ParamID id, TimeValue t=0, int tabIndex=0)

PB2Export Texmap *	GetTexmap (ParamID id, TimeValue t=0, int tabIndex=0)

PB2Export PBBitmap *	GetBitmap (ParamID id, TimeValue t=0, int tabIndex=0)

PB2Export INode *	GetINode (ParamID id, TimeValue t=0, int tabIndex=0)

PB2Export ReferenceTarget *	GetReferenceTarget (ParamID id, TimeValue t=0, int tabIndex=0)

PB2Export IParamBlock2 *	GetParamBlock2 (ParamID id, TimeValue t=0, int tabIndex=0)

PB2Export Matrix3	GetMatrix3 (ParamID id, TimeValue t=0, int tabIndex=0)

PB2Export const MCHAR *	GetString (StringResID id)

PB2Export void	InvalidateUI ()

PB2Export void	InvalidateUI (ParamID id, int tabIndex=-1)

PB2Export void	SetUserDlgProc (MapID map_id, ParamMap2UserDlgProc *proc=NULL)

void	SetUserDlgProc (ParamMap2UserDlgProc *proc=NULL)

PB2Export ParamMap2UserDlgProc *	GetUserDlgProc (MapID id=0)

PB2Export void	SetOwnerRefNo (ParamID id, int refno)

PB2Export int	GetOwnerRefNo (ParamID id)

PB2Export void	SetSubTexNo (ParamID id, int texno)

PB2Export void	SetSubMtlNo (ParamID id, int mtlno)

PB2Export int	GetSubTexNo (ParamID id)

PB2Export int	GetSubMtlNo (ParamID id)

PB2Export void	SetInitFile (ParamID id, const MCHAR *s)

PB2Export const MCHAR *	GetInitFile (ParamID id)

PB2Export void	AddInterface (BaseInterface *iface)
	Adds an interface to the descriptor's BaseInterfaceServer interfaces list. More...

PB2Export void	RemoveInterface (BaseInterface *iface)
	Removes an interface from the descriptor's BaseInterfaceServer interfaces list. More...

PB2Export void	SetFileTypes (ParamID id, const MCHAR *fileType)
	Allows a custom filter list to be supplied to the File dialog routines. More...

Public Member Functions inherited from BaseInterfaceServer
virtual UtilExport BaseInterface *	GetInterface (Interface_ID id)

virtual UtilExport int	NumInterfaces () const

virtual UtilExport BaseInterface *	GetInterfaceAt (int i) const

virtual UtilExport	~BaseInterfaceServer ()

Public Member Functions inherited from InterfaceServer
virtual UtilExport	~InterfaceServer ()
	Destructor. More...

Public Attributes
ParamDef *	paramdefs

ClassDesc2 *	cd

const MSTR	int_name

StringResID	local_name

BlockID	ID

USHORT	count

ULONG	version

USHORT	flags

int	ref_no

int	dlg_template

int	title

int	test_flags

int	rollup_flags

ParamMap2UserDlgProc *	dlgProc

int	category

Tab< map_spec >	map_specs

MSPluginClass *	pc

Rollout *	rollout

IParamBlock2 *	class_params

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...

static UtilExport void *	aligned_malloc (size_t size, size_t alignment)
	Allocates memory on a specified alignment boundary. More...

static UtilExport void *	aligned_realloc (void *ptr, size_t size, size_t alignment)
	Reallocates memory on a specified alignment boundary. More...

static UtilExport void	aligned_free (void *ptr)
	Frees a block of memory that was allocated with aligned_malloc/aligned_realloc. More...

Protected Member Functions inherited from Noncopyable
	Noncopyable ()

	~Noncopyable ()

Protected Attributes inherited from BaseInterfaceServer
Tab< BaseInterface * >	interfaces

Constructor & Destructor Documentation

ParamBlockDesc2 ( )

PB2Export ParamBlockDesc2	(	BlockID	ID,
		const MCHAR *	int_name,
		StringResID	local_name,
		ClassDesc2 *	cd,
		USHORT	flags,
			...
	)

Remarks: This constructor takes a number of fixed, block-related arguments and then a varargs-based variable list of arguments that define the block and its parameters.

The format of the definitions in this shown below, but basically is in the form of a sequence of fixed specs followed by a variable number of tagged optional specs for each parameter.

Parameters:

The generic form for the parameters of this constructor is shown below:

ParamBlockDesc2 (
<required_block_specs> ,
[<version_number> ,]
[<auto_construct_block_refno> ,]
[<auto_ui_parammap_specs> ,]
{<required_param_specs> ,
{<optional_tagged_param_specs> ,}
end
,}
end);

That is:

Required block specs & per-block flags, followed by,
Optional version number if P_Version is set, followed by,
Optional owning object reference number for the block if auto-construct, followed by,
Optional parameter map specs if auto-ui, followed by,
Zero or more parameter specs, comprising:
a. Required parameter specs, followed by,
b. Zero or more optional parameter specs, each with is own leading tag, the list terminated by an 'end' tag, followed by,
an 'end' tag

<required_block_spec>

The following required first arguments to the constructor form the "required_block_spec" and "per block flags":

BlockID ID
The permanent block ID for the parameter block2.

MCHAR* int_name
The internal name string. This name is not localized. Internal names are meant to be parsable as identifiers. As such they should begin with an alpha character, have only alphanumerics, and have no spaces, punctuations, etc. The convention for multi-word names is to use studly-caps, eg, paintRadius.

int local_name
The resource ID of the localized (sub-anim) name string.

ClassDesc2* cd
Points to the class descriptor2 of the owning class. This is used to add this descriptor to the ClassDesc2's table of block descriptors for the class. Note: This value may be passed as NULL for situations where the blocks owning ClassDesc2 is not available for static initializations (such as in a separate file). Before using the descriptor for any block construction, the ClassDesc2* must be initialized with the method:
void ParamBlockDesc2::SetClassDesc(ClassDesc2* cd);
You can only call this method once on a descriptor and then only if it has been constructed initially with a NULL cd.

BYTE flags
Per block/descriptor flags. One or more of the following values (they may be added together as in P_AUTO_CONSTRUCT + P_AUTO_UI).

P_VERSION
New in max 8. When used as a ParamBlockDesc2 flag, a version number is expected immediately after the flags field, before the reference number field. This version number will be stored as ParamBlockDesc2::version and returned as IParamBlock2::GetVersion().
P_CLASS_PARAMS
Indicates this block holds class-level parameters which are attached to the ClassDesc2 for the plug-in. Such class level parameters are shared by each instance of the class. The block is automatically allocated by and stored in the descriptor. You get at its parameters via GetValue()/SetValue() calls on the descriptor.
P_AUTO_CONSTRUCT
Indicates the parameter block2 will be constructed and referenced automatically to its owner in the call to ClassDesc2::MakeAutoParamBlocks(). If this flag is set, the parameter block's reference number in the owning object should be given immediately following the flag word in the descriptor constructor. See <auto_construct_block_refno> .
P_AUTO_UI
Indicates this block supports automatic UI rollout management in calls to ClassDesc2::BeginEditParams(), ClassDesc2::EndEditParams(),ClassDesc2::CreateParamDlg(), ClassDesc2::CreateParamDialog(), etc.
If set, the <auto_ui_parammap_specs> must be supplied in the descriptor constructor.
P_AUTO_UI_QT
Indicates this block supports automatic UI rollout management (using QT) in calls to ClassDesc2::BeginEditParams(), ClassDesc2::EndEditParams(),ClassDesc2::CreateParamDlg(), ClassDesc2::CreateParamDialog(), etc.
No arguments must be supplied to supplement this flag (unlike P_AUTO_UI which requires a dialog ID, etc.).
P_HASCATEGORY
The category field that can be used to order rollups (see Class IRollupWindow) to various Parameter Map creation methods. In order to use the category field with AutoUI, this flag has to be declared together with P_AUTO_UI in the ParamBlockDesc2. An additional int, that describes the category has to be appended to the parameter list after the ParamMap2UserDlgProc* proc parameter. The same thing is true for multimaps. The P_HASCATEGORY field can only be declared for the whole pblock. That means, that every multimap has to have the category parameter. To use the standard value ROLLUP_CAT_STANDARD can be used. In the example below 4900 is used as the integer describing the category;

static ParamBlockDesc2 std2_shader_blk ( std2_shader,

_M("shaderParameters"), 0, &stdmtl2CD,

P_AUTO_CONSTRUCT + P_AUTO_UI + P_HASCATEGORY, SHADER_PB_REF,

//rollout

IDD_DMTL_SHADER4, IDS_KE_SHADER, 0, 0, &shaderDlgProc, 4900,

// params

std2_shader_type, _M("shaderType"), TYPE_INT, 0, IDS_JW_SHADERTYPE,
P_USE_PARAMS
Indicates that this block shares (exactly) the paramdefs from another descriptor. This is used to specify an already established ParamBlockDesc2 instance whose parameters you wish to share. This effectively gives the referring descriptor a pointer to the established descriptors 'paramdefs' array. In this case no other parameters definition can be supplied to referencing descriptors constructor. See the sample code below.
P_INCLUDE_PARAMS
Indicates that this block loads in a copy the paramdefs from another descriptor. This is used to take a copy of an already established descriptor's parameters, to which you can add extra parameter definitions in the referencing descriptors constructor. This provides a kind of poor-man's factoring of common parameters, but note it is a copy; any subsequent changes to the established descriptor's parameter definitions are not reflected in the referencing descriptor.

You give the pointer to the ParamBlockDesc2 supplying the existing parameter definitions following the other optional block-level parameters: following the flag word is the block's reference number if P_AUTO_CONSTRUCT is specified, then the rollout dialog template info if P_AUTO_UI is specified, then the pointer to the sourcing descriptor if P_USE_PARAMS or P_INCLUDE_PARAMS is specified. For example:

static ParamBlockDesc2 metal2_param_blk ( shdr_params, _M("shaderParameters"), 0, &metalCD, P_AUTO_CONSTRUCT + P_USE_PARAMS,

// pblock refno 0,

// use params from existing descriptor

&const_param_blk

);
P_SCRIPTED_CLASS
This is for internal use only. It means that the descriptor was defined on the fly as a side-effect of writing a scripted plug-in.
P_TEMPORARY
This is for internal use only.
P_TEMPLATE_UI
This indicates that dialog templates will be provided or constructed.
P_CALLSETS_ON_LOAD
Signals that this block should have CallSets() called on it during post-load processing on scene loads & merges. This effectively ensures that all PBAccessor::Set() methods will be called after the flagged pblock2 is fully loaded, so that they can track loaded param values, for example. This allows a single point of param value tracking in the PBAccessor::Set() and precludes the need for individual objects to implement PLCBs to do this tracking themselves.
P_MULTIMAP
Indicates that the block being described will have more than one rollup/map. If you specify this flag, the constructor interprets the rollup template and parameter definitions arguments in a modified syntax. Here's a sample rework of the main pblock in GeoSphere into two rollups:

enum { geo_map_1, geo_map_2 }; // enum IDs for the 2 parammaps

static ParamBlockDesc2 geo_param_blk ( geo_params, _M("GeosphereParameters"),

0, &gsphereDesc, P_AUTO_CONSTRUCT +

P_AUTO_UI + P_MULTIMAP, PBLOCK_REF_NO,

// map rollups

2,

geo_map_1, IDD_GSPHERE_1, IDS_PARAMETERS_1, 0, 0, NULL,

geo_map_2, IDD_GSPHERE_2, IDS_PARAMETERS_2, 0, 0, NULL,

// params

geo_hemi, _M("hemisphere"), TYPE_BOOL, P_ANIMATABLE, IDS_HEMI,

p_default, FALSE,

p_ui, geo_map_2, TYPE_SINGLECHECKBOX, IDC_HEMI,

end,

geo_segs, _M("segs"), TYPE_INT, P_ANIMATABLE, IDS_RB_SEGS,

p_default, 4,

p_range, MIN_SEGMENTS, MAX_SEGMENTS,

p_ui, geo_map_1, TYPE_SPINNER, EDITTYPE_INT,

IDC_SEGMENTS, IDC_SEGSPINNER, 0.05f,

end,

geo_radius, _M("radius"), TYPE_FLOAT, P_ANIMATABLE + P_RESET_DEFAULT, IDS_RB_RADIUS,

p_default, 0.0,

p_ms_default, 25.0,

p_range, MIN_RADIUS, MAX_RADIUS,

p_ui, geo_map_1, TYPE_SPINNER, EDITTYPE_UNIVERSE,

IDC_RADIUS, IDC_RADSPINNER, 1.0,

p_uix, geo_map_2,

end,

//...

First, there is an enum to provide IDs for the two maps in the main block, geo_map_1 and geo_map_2. The P_MULTIMAP flag is added to the block flags in the main descriptor constructor arguments to indicate multiple parameter maps present. If P_AUTO_UI or P_AUTO_UI_QT is specified, the usual single rollup template spec is replaced by a count (of rollups) followed by that many sets of rollup specs (which are empty for P_AUTO_UI_QT), each beginning with the associated mapID. The auto UI mechanism will add the rollups in the order given in this list.

In the parameter definition section, the only change is to the p_ui option, which now requires a map ID before the rest of the UI specification to say which rollup/map the spec relates to. In this case, we've put the hemisphere checkbox in the 2nd rollup and the segments (segs) and radius spinners in the first.

There is also a new option, p_uix, which is used to say that the parameter is to appear in more than one rollup. In this case, the radius spinner also shows up in the 2nd rollup, geo_map_2. When you do this, all the controls that connect to this parameter are ganged together; they all change when any one of them changes and all show keyframe highlights and so on. The current limitations on this are that the type of UI control and its various dialog template item IDs must be the same in each rollup in which it appears.

[<version_number>]: If P_VERSION is used as a ParamBlockDesc2 flag, a version number is expected immediately after the flags field, before the reference number field. This version number will be stored as ParamBlockDesc2::version and returned as IParamBlock2::GetVersion()

[<auto_construct_block_refno>]

If P_AUTO_CONSTRUCT is specified in the required per block / descriptor flags (BYTE flags above) then the integer reference number of the parameter block2 in the plug-in needs to be specified:

int ref_no
This is the same number that the plug-in would use to get and set the parameter block reference in GetReference() and SetReference().

[<auto_ui_parammap_specs>]

If P_AUTO_UI is specified in the required per block / descriptor flags (BYTE flags above) then the following arguments to the constructor are required:

int dialog_template_ID,
int dialog_title_res_ID,
int flag_mask,
int rollup_flags,
ParamMap2UserDlgProc* proc

Each of these is described below:

int dialog_template_ID
The ID of the dialog template (eg IDD_something).
int dialog_title_res_ID
The string table resource ID for the title of the dialog.
int flag_mask
This is used by ClassDesc2::BeginEditParams() and ClassDesc2::EndEditParams() to determine whether the ParamMap2 should be created/deleted on this call. All the bits in the supplied mask must be on in the Begin/EndEditParams flag longword for the action to take place.
int rollup_flags
This flag is used to control rollup creation. You may pass:
APPENDROLL_CLOSED
to have the rollup added in the closed (rolled up) state. Otherwise pass 0.
ParamMap2UserDlgProc* proc
If there are controls in the dialog that require special processing this user dialog proc can be implemented to process them. See Class ParamMap2UserDlgProc. If not used then NULL should be passed.

<required_param_specs>

The required parameter spec is formatted as shown below. There is one of these for each of the controls managed by the parameter map. They are followed by an <optional_tagged_param_spec>.

ParamID id,
MCHAR* internal_name,
ParamType type,
[int table_size,]
int flags,
int local_name_res_ID,

Each of these is described below:

ParamID id
The permanent, position-independent ID for the parameter.
MCHAR* internal_name
The internal name for the parameter.
ParamType type
The type of parameter. See List of ParamType Choices.
[int table_size]
If the type is one of the Tab<> types, you need to supply an initial table size which can be 0.
int flags
The per parameter flag bits. This should be a bitwise OR of one or more of the following:

P_ANIMATABLE
Indicates the parameter is animatable.

P_TRANSIENT
Indicates the parameter should not be saved in the scene file. One might do this, for example, for virtual parameters that don't actually hold data but reflect data held elsewhere in the object (and accessed via a PBAccessor) which is saved explicitly by it. This might save file space. In some cases, parameters might be provided that are derived from other state in the object that is computed each time you load the object and made available say as a help to script authors. In these cases also, you might decide not to take up file space.

P_NO_INIT
This is obsolete.

P_COMPUTED_NAME
Indicates to call a compute name function to get a dynamically-computed name. This allows a plug-in to provide a dynamically-created local name for a parameter or Tab<> parameter entry. If you specify this parameter flag, you also need to supply a p_accessor PBAccessor instance pointer that has the GetLocalName() method implemented.

P_INVISIBLE
Not visible in track view (if an animatable).

P_RESET_DEFAULT
Indicates to not make creation parameters sticky, rather always reset to default values.

P_SUBANIM
Indicates this is a non-animatable reference target parameter to be published as a sub-anim (which makes it visible in Track View)

P_TV_SHOW_ALL
This is used for Tab<> animatables, and indicates to show all entries in Track View even if no controller assigned.

P_NO_REF
For reference target parameters, this indicates to not maintain the reference automatically (rather simply keep a copy of the pointer).

P_OWNERS_REF
Indicates this is a reference target parameter owned by the parameter block's owner not the block itself. Make sure to supply the owner's reference number in a p_refno specification. If neither p_refno or P_OWNERS_REF is set, the parameter block owns and maintains the reference.

P_CAN_CONVERT
Indicates the p_classID validator is used in a CanConvertoTo() call, rather than as exact classID match.

P_SUBTEX
Indicates a texmap parameter is kept by the owner using the MtlBase::xSubTexmap methods. Provide the integer index of the sub-texmap using the param tag p_subtexno.

You would use this flag in materials or texmaps that contain other texmaps as parameters, in which these 'sub' maps are not stored in the ParamBlock2 and are not accessible as direct references on the parent map or material, but are accessible via the MtlBase::GetSubTexmap()/SetSubTexmap() protocol.

Specifying this P_SUBTEX flag signals this situation and looks for a p_subtexno parameter option to give the sub-texmap number for the map. For example, the Standard material stores all its maps in a separate structure that appears as a single reference in the Standard material. In this case, the individual texmaps are not direct references on the material, but are accessible on the material via GetSubTexmap()/SetSubTexmap().

Note that P_OWNERS_REF and P_SUBTEX are both primarily intended for use when re-coding existing plug-ins in which the sub-maps are already managed by the owner in some way. If you are implementing a new plug-in, you should just let the ParamBlock2 host them for you and then you don't have to bother with either of these flags.

P_VARIABLE_SIZE
Indicates a Tab<> parameter is variable in size. This allows scripted changes.

P_NO_AUTO_LABELS
Disables the automatic setting of button text for texmaps, materials, files, etc. You can use the method IParamMap2::SetText() to set it by hand.

P_SHORT_LABELS
This is for use with TYPE_TEXMAP, TYPE_MTL and TYPE_BITMAP parameters that are associated with ParamMap2 picker buttons. If you specify this flag, a shortened form of the object name is installed in the picker button label. For texmaps and materials, the MtlBase::GetName() rather than MtlBase::GetFullName() is used, and for bitmaps just the filename rather than the full pathname is used.

P_READ_ONLY
This parameter is not assignable through MAXScript. It allows try-and-buy 3rd-party plugins.

P_OBSOLETE
New in Max 8.0. When used as a ParamBlockDesc2 param flag, the param will not be saved to disk or maintain references or animation keys. When loading older files, the parameter will be reset after the load is completed, but will be valid during a post-load callback

P_READ_SECOND_FLAG_VALUE
Indicates that a second DWORD sized flag value follows the first in the parameter's definition. The second flag will be read in, shifted left DWORD*8 bits and combined with the first flag value to form the ParamDef flag value.

Second Flag Values

P_USE_ACCESSOR_ONLY
When set, 3ds Max will get or set the value of the parameter this flag is applied to only via the accessor function, if available.

P_USE_NODE_TM_VALIDITY
When set, the parameter block's validity interval is intersected with that of the Node parameter's transform. Applies only to TYPE_INODE and TYPE_INODE_TAB parameters.

P_USE_NODE_OS_VALIDITY
When set, the parameter block's validity interval is intersected with that of the Node parameter's object state (including the world space modifiers). Applies only to TYPE_INODE and TYPE_INODE_TAB parameters.

P_NO_MACRO_RECORDER
When set, changes to the parameter will not trigger output to the macro recorder.
int local_name_res_ID
The localized name for the parameter. This is a ID for the resource in the string table.

<optional_tagged_param_specs>: There may be zero or more optional tagged parameter specs, each with its own leading tag, with the entire list terminated by an 'end' tag. This list of tagged arguments has the following form:
<tag>, <optional_param_spec>,
For the possible tags and the specification arguments see List of ParamTags Choices.

PB2Export ~ParamBlockDesc2 ( )

Member Function Documentation

PB2Export void AddParam	(	ParamID	id,
			...
	)

Remarks: This method is used for building descriptors incrementally. It adds a parameter to an existing descriptor.

Note that you must not modify a descriptor with this function once it has been used to construct a ParamBlock2 (for instance in object creation); there is no version control in place and crashes or unpredictable results can occur.

Parameters:: ParamID id, ...

This function takes a single parameter definition in exactly the same varargs format as the ParamBlockDesc2 constructor. See the Constructors section.

PB2Export void ReplaceParam	(	ParamID	id,
			...
	)

Remarks: This method is used for modifying a descriptors incrementally. It overrides an existing parameter definition of same ID passed. Note: You must not modify a descriptor with this method once it has been used to construct a ParamBlock2.

Parameters:: ParamID id, ...

This function takes a single parameter definition in exactly the same varargs format as the ParamBlockDesc2 constructor. See the Constructors section.

void DeleteParam ( ParamID id )

inline

Remarks: Deletes the specified parameter from the descriptor.

Parameters:: ParamID id

The permanent ID of the parameter to delete.

3422 { int i = IDtoIndex(id); DbgAssert(i >= 0); DeleteParamByIndex(i); }

ParamBlockDesc2::DeleteParamByIndex

PB2Export void DeleteParamByIndex(int index)

ParamBlockDesc2::IDtoIndex

PB2Export int IDtoIndex(ParamID id)

DbgAssert

#define DbgAssert(expr)

Definition: assert1.h:72

PB2Export void DeleteParamByIndex ( int index )

Remarks: Deletes the specified parameter from the descriptor.

Parameters:: int index

The index of the parameter to delete.

PB2Export void DeleteAllParams ( )

Remarks: Deletes all parameters from the descriptor.

PB2Export void ParamOption	(	ParamID	id,
		int	option_tag,
			...
	)

Remarks: This method is used for modifying a descriptor incrementally. It alters a parameter definition optional information tag of an existing descriptor. Note: You must not modify a descriptor with this method once it has been used to construct a ParamBlock2.

Parameters:: ParamID id

The permanent ID of the parameter.

int option_tag, ...

This method takes a single tagged option in the same varargs format as the tagged parameter options in the ParamBlockDesc2 constructor. See the <optional_tagged_param_specs> section in the constructor's documentation.

PB2Export bool ParamOptionEnableCtrls	(	ParamID	pID,
		const Tab< ParamID > &	dependentPIDs
	)

Modifies the list of controls enabled by a certain control This method allows to modify the list of controls that are enabled/disabled by a given control that represents a boolean parameter.

Any existent list of dependent controls are replaced.

pID The identifier of the control to be modified. The id must designate a control in this parameter block descriptor.

dependentPIDs Identifiers that depend on the control specified by pID.: The parameters must be part of the same parameter block descriptor as the parameter that controls them (pID).

Returns: True if the control was modified successfully, false otherwise

Note: A parameter descriptor should not be modified after a parameter block has been created based on it.

PB2Export bool ParamOptionContentValues	(	ParamID	id,
		Tab< int > &	stringItems,
		Tab< int > *	stringItemValues = `NULL`
	)

This method is used for modifying a descriptor incrementally.

It allows for specifying the content of certain controls such as list and combo boxes by supplying a list of string resource ids. This method alters a parameter definition optional information tag of an existing descriptor. Note: You must not modify a descriptor with this method once it has been used to construct a ParamBlock2.

Parameters

id	- The permanent ID of the parameter to be modified
stringItems	- Resource ids of the strings that represent the user visible values for this parameters
stringItemValues	- Optional list of integer values to be associated with the corresponding item in the stringItems parameter. If this parameter is not specified, the items in stringItems will be associated with their zero based index.

PB2Export void SetClassDesc ( ClassDesc2 * pCD )

Remarks: This method sets the ClassDesc2 pointer maintained by this class. You can only call this method once on a descriptor and then only if it has been constructed initially with a NULL cd. See the notes in the constructor.

Parameters:: ClassDesc2* pCD

Points to the ClassDesc to set.

USHORT Count ( )

inline

Remarks: Returns the number of parameters in the block.

3482 { return count; }

ParamBlockDesc2::count

USHORT count

Definition: iparamb2.h:3028

DWORD Version ( )

inline

Remarks: Returns the version of the parameter block.

3484 { return version; }

ParamBlockDesc2::version

ULONG version

Definition: iparamb2.h:3029

PB2Export int IDtoIndex ( ParamID id )

Remarks: Returns the index into the parameter definition array of the parameter whose ID passed.

Parameters:: ParamID id

The permanent parameter ID.

PB2Export int NameToIndex ( const MCHAR * name )

Finds the parameter with the matching internal name (ParamDef::int_name), and returns its index.

Returns -1 is the parameter is not found.

Remarks: The name comparison is case-insensitive.

Parameters

name	The internal name of the parameter to find (see ParamDef::int_name)

ParamID IndextoID ( int i )

inline

Remarks: Returns the permanent parameter ID of the parameter whose index is passed.

Parameters:: int i

The zero based index of the parameter in the paramdefs array.

3500 { return (((i >= 0) && (i < Count())) ? paramdefs[i].ID : -1); }

ParamBlockDesc2::paramdefs

ParamDef * paramdefs

Definition: iparamb2.h:3023

ParamBlockDesc2::ID

BlockID ID

Definition: iparamb2.h:3027

ParamBlockDesc2::Count

USHORT Count()

Definition: iparamb2.h:3482

ParamDef& GetParamDef ( ParamID id )

inline

Remarks: This method is used for accessing a parameter's ParamDef structure.

Parameters:: ParamID id

The permanent ID of the parameter.

3506 { int i = IDtoIndex(id); DbgAssert(i >= 0); return paramdefs[i]; }

ParamBlockDesc2::paramdefs

ParamDef * paramdefs

Definition: iparamb2.h:3023

ParamBlockDesc2::IDtoIndex

PB2Export int IDtoIndex(ParamID id)

DbgAssert

#define DbgAssert(expr)

Definition: assert1.h:72

const ParamDef * GetParamDefByIndex ( const unsigned int parameterIndex ) const

inline

Returns the parameter definition for the parameter with the given index.

Parameters

parameterIndex Index of the parameter to be fetched.

Returns: A pointer to the parameter definition for the given index, or null if the index is invalid.

 {
     if(DbgVerify((paramdefs != nullptr) && (parameterIndex < count)))
     {
         return &(paramdefs[parameterIndex]);
     }
     else
     {
         return nullptr;
     }
 }

BOOL SetValue	(	ParamID	id,
		TimeValue	t,
		float	v,
		int	tabIndex = `0`
	)

inline

Remarks: This method is used with static class parameter blocks only.

Sets the floating point value of the specified parameter at the specified time.

Parameters:: ParamID id

The permanent ID of the parameter.

TimeValue t

The time at which to set the value.

float v

The value to set.

int tabIndex=0

If the parameter is a Tab<> this is the zero based index into the table of the value to set.

Returns: TRUE on success; otherwise FALSE.

3529 { return class_params->SetValue(id, t, v, tabIndex); }

IParamBlock2::SetValue

virtual BOOL SetValue(ParamID id, TimeValue t, float v, int tabIndex=0)=0

PB2Export Color GetColor	(	ParamID	id,
		TimeValue	t = `0`,
		int	tabIndex = `0`
	)

PB2Export AColor GetAColor	(	ParamID	id,
		TimeValue	t = `0`,
		int	tabIndex = `0`
	)

PB2Export Point2 GetPoint2	(	ParamID	id,
		TimeValue	t = `0`,
		int	tabIndex = `0`
	)

PB2Export Point3 GetPoint3	(	ParamID	id,
		TimeValue	t = `0`,
		int	tabIndex = `0`
	)

PB2Export Point4 GetPoint4	(	ParamID	id,
		TimeValue	t = `0`,
		int	tabIndex = `0`
	)

PB2Export int GetInt	(	ParamID	id,
		TimeValue	t = `0`,
		int	tabIndex = `0`
	)

PB2Export float GetFloat	(	ParamID	id,
		TimeValue	t = `0`,
		int	tabIndex = `0`
	)

PB2Export TimeValue GetTimeValue	(	ParamID	id,
		TimeValue	t = `0`,
		int	tabIndex = `0`
	)

PB2Export const MCHAR* GetStr	(	ParamID	id,
		TimeValue	t = `0`,
		int	tabIndex = `0`
	)

PB2Export Mtl* GetMtl	(	ParamID	id,
		TimeValue	t = `0`,
		int	tabIndex = `0`
	)

PB2Export Texmap* GetTexmap	(	ParamID	id,
		TimeValue	t = `0`,
		int	tabIndex = `0`
	)

PB2Export PBBitmap* GetBitmap	(	ParamID	id,
		TimeValue	t = `0`,
		int	tabIndex = `0`
	)

PB2Export INode* GetINode	(	ParamID	id,
		TimeValue	t = `0`,
		int	tabIndex = `0`
	)

PB2Export ReferenceTarget* GetReferenceTarget	(	ParamID	id,
		TimeValue	t = `0`,
		int	tabIndex = `0`
	)

PB2Export IParamBlock2* GetParamBlock2	(	ParamID	id,
		TimeValue	t = `0`,
		int	tabIndex = `0`
	)

PB2Export Matrix3 GetMatrix3	(	ParamID	id,
		TimeValue	t = `0`,
		int	tabIndex = `0`
	)

PB2Export void SetUserDlgProc	(	MapID	map_id,
		ParamMap2UserDlgProc *	proc = `NULL`
	)

PB2Export void SetFileTypes	(	ParamID	id,
		const MCHAR *	fileType
	)

id	The parameter that defines a file dialog
fileType	A string containing a correctly formatted filter list. This buffer is maintained by the calling code

ParamBlockDesc2 Class Reference

Class Description

Classes

Public Member Functions

Public Attributes

Additional Inherited Members

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation