This reference page is linked to from the following overview topics: Common Build Problems.

#include <xsi_ppglayout.h>

Class Description

The PPGLayout object represents the visual appearance of an object's state when it is inspected. (PPG is a common acronym for Property Page). The layout makes it possible to group objects together, use special controls, hide obsolete parameters, add Buttons and in general create a presentation of an object's state that is pleasing to the eye.

A PPGLayout is modeled in Softimage as a linear list of PPGItem objects. Each PPGItem represents either a parameter in the inspected object, or a special UI item like a Tab or Button. In most cases the layout does not specify hard-coded pixel positions or dimensions for the PPGItems. Instead, Softimage automatically draws the controls with a sensible layout. This allows the presentation to change in a pleasing manner when the user resizes the property page. However there is some support for providing hints, for example PPGItem::PutWidthPercentage, or even explicit sizes via PPGItem::PutAttribute.

Many different controls are available for use on a property page, see ::siPPGControlType. All controls can be added using PPGLayout::AddItem but convenience functions are provided for some of the most common controls, for example PPGLayout::AddColor.

Practically every built-in Softimage object has its own layout. However, if there is no specific layout, Softimage displays a default layout that lists all the parameters in a simple fashion.

Layouts are remembered in memory while Softimage is running. The layouts for built-in objects are reloaded from SPDL files when Softimage restarts. The layout for a CustomProperty object implemented as a PluginItem is defined by implementing the DefineLayout callback.

You cannot directly modify an existing layout structure, apart from adding new items at the end or changing the attributes of items already in the layout. However to modify a layout it is often reasonable to call PPGLayout::Clear and then rebuild the entire layout with the changes included. You can also hide parameters without removing them from the layout by setting the siNotInspectable flag (see Parameter::PutCapabilityFlag).

Note:: If the layout is changed from within the PPGEvent callback it is necessary to set the Refresh attribute to see the changes take effect. (see PPGEventContext).

Normally the layout is associated with an object that remains in the scene. However it is also possible to use this object to define the user interface of a temporary dialog box. For example a script can ask the user to specify some import or export options. This is done in conjunction with a temporary CustomProperty object and the InspectObj command.

See also:: PPGItem, ProjectItem::GetPPGLayout, PPGEventContext, PluginRegistrar::RegisterProperty, Building Dialogs, PSetUIDemo example

Since:: 4.0

Example:

                using namespace XSI;
                Application app;
                Model root = app.GetActiveSceneRoot();

                // Step 1: Create a custom pset and define the data on it
                CustomProperty oPSet ;
                root.AddProperty( L"CustomProperty", false, L"Demo", oPSet) ;

                Parameter param ;

                // Color is made up of 4 components
                oPSet.AddParameter( L"MyR", CValue::siDouble, siPersistable, L"", L"", 0.0,0.0,1.0,0.0,1.0, param ) ;
                oPSet.AddParameter( L"MyG", CValue::siDouble, siPersistable, L"", L"", 0.0,0.0,1.0,0.0,1.0, param ) ;
                oPSet.AddParameter( L"MyB", CValue::siDouble, siPersistable, L"", L"", 0.0,0.0,1.0,0.0,1.0, param ) ;
                oPSet.AddParameter( L"MyA", CValue::siDouble, siPersistable, L"", L"", 0.0,0.0,1.0,0.0,1.0, param ) ;

                oPSet.AddParameter( L"EnumCtrl", CValue::siInt4, siPersistable, L"", L"", 4l,4l,6l,4l,6l, param ) ;

                PPGLayout oPPGLayout = oPSet.GetPPGLayout() ;
                oPPGLayout.AddGroup( L"Pick a Color" ) ;

                PPGItem oItem = oPPGLayout.AddColor( L"MyR", L"", true ) ;
                oItem.PutAttribute( siUINoLabel, true ) ;

                oPPGLayout.EndGroup() ;

                CValueArray uiItems(4) ;
                uiItems[0] = L"item 1" ; uiItems[1] = 4l;
                uiItems[2] = L"item 2" ; uiItems[3] = 6l;

                oItem = oPPGLayout.AddEnumControl(
                                                L"EnumCtrl",
                                                uiItems,
                                                L"Choice",
                                                siControlCombo ) ;


                // Step 3: Show the user the dialog.  They can change the
                // parameter values and then click OK or Cancel

                CValueArray args(5) ;
                args[0] = oPSet ;
                args[2] = L"Check out this layout created from C++" ;
                args[3] = (LONG)siModal ;
                args[4] = false ;

                CValue retval ;

                app.ExecuteCommand( L"InspectObj", args, retval ) ;

                if ( !(bool)retval )
                {
                        // Step 4: Read the values and do something with them.  Normally this
                        //      would be where you call a custom command which does the operation

                        app.LogMessage( L"User picked the color (" +
                                        oPSet.GetParameterValue( L"MyR" ).GetAsText() + L"," +
                                        oPSet.GetParameterValue( L"MyG" ).GetAsText() + L"," +
                                        oPSet.GetParameterValue( L"MyB" ).GetAsText() + L"," +
                                        oPSet.GetParameterValue( L"MyA" ).GetAsText() +
                                        L")" ) ;

                        if ( oPSet.GetParameterValue( L"EnumCtrl" ) == 4l )
                        {
                                app.LogMessage( L"User selected item 1" ) ;
                        }
                        else
                        {
                                app.LogMessage( L"User selected item 2" ) ;
                        }
                }
                else
                {
                        app.LogMessage( L"User cancelled" ) ;
                }

                //Step 5: Remove the pset now that we are done with it

                CValueArray deleteargs(1) ;
                deleteargs[0] = oPSet ;
                app.ExecuteCommand( L"DeleteObj", deleteargs, retval ) ;

Inheritance diagram for PPGLayout:

List of all members.

Public Member Functions
	PPGLayout ()
	~PPGLayout ()
	PPGLayout (const CRef &in_ref)
	PPGLayout (const PPGLayout &in_obj)
bool	IsA (siClassID in_ClassID) const
siClassID	GetClassID () const
PPGLayout &	operator= (const PPGLayout &in_obj)
PPGLayout &	operator= (const CRef &in_ref)
PPGItem	AddItem (const CString &in_ParamName, const CString &in_Label=CString(), const CString &in_Type=CString())
PPGItem	AddString (const CString &in_ParamName, const CString &in_Label=CString(), bool in_Multiline=false, LONG in_Height=120)
PPGItem	AddEnumControl (const CString &in_ParamName, const CValueArray &in_UIItemsArray, const CString &in_Label=CString(), const CString &in_UIType=CString(L"Combo"))
PPGItem	AddColor (const CString &in_RedComponentParamName, const CString &in_Label=CString(), bool in_Alpha=false)
PPGItem	AddButton (const CString &in_ScriptName, const CString &in_Label=CString())
PPGItem	AddFCurve (const CString &in_ScriptName, LONG in_Height=300)
PPGItem	AddStaticText (const CString &in_Text, LONG in_Width=0, LONG in_Height=0)
PPGItem	AddSpacer (LONG in_Width=0, LONG in_Height=0)
CStatus	Clear ()
CStatus	Delete ()
CStatus	AddRow ()
CStatus	EndRow ()
PPGItem	AddGroup (const CString &in_Label=CString(), bool in_ShowFrame=true, LONG in_WidthPercentage=0)
PPGItem	EndGroup ()
PPGItem	AddTab (const CString &in_Label)
CStatus	SetViewPosition (LONG in_posX, LONG in_posY)
CStatus	GetViewPosition (LONG &out_posX, LONG &out_posY) const
CStatus	SetViewSize (LONG in_width, LONG in_height)
CStatus	GetViewSize (LONG &out_width, LONG &out_height) const
CString	GetLogic () const
CStatus	PutLogic (const CString &in_strLogic)
CString	GetLanguage () const
CStatus	PutLanguage (const CString &in_strLogicLang)
CStatus	PutAttribute (const CString &in_UIAttribute, const CValue &in_AttributeValue)
CValue	GetAttribute (const CString &in_UIAttribute) const
PPGItem	GetItem (const CString &in_Name) const
PPGItem	GetItem (LONG in_Index) const
LONG	GetCount () const

Constructor & Destructor Documentation

PPGLayout ( )

Default constructor.

~PPGLayout ( )

Default destructor.

PPGLayout ( const CRef & in_ref )

Constructor.

Parameters:

in_ref constant reference object.

PPGLayout ( const PPGLayout & in_obj )

Copy constructor.

Parameters:

in_obj constant class object.

Member Function Documentation

bool IsA ( siClassID in_ClassID ) const [virtual]

PPGItem AddItem	(	const CString &	in_ParamName,
		const CString &	in_Label = `CString()`,
		const CString &	in_Type = `CString()`
	)

in_ParamName	Scripting name of the Parameter. The call does not fail even if no parameter by this name exists. However in that case the control is not drawn as part of the layout. (See PPGItem::GetName).
in_Label	Most controls have a label, for example the text that appears to the left of a numeric slider. If not specified here, the value returned from SIObject::GetName or Parameter::GetScriptName is shown instead. (See PPGItem::GetLabel).
in_Type	Specify the control to draw. A complete list of possible controls is listed in the siPPGControlType string constants. For example this argument can be used to specify that a parameter should be displayed as a combo box. (See PPGItem::GetType). If not specified, Softimage uses a simple heuristic for determining what control to use, based on the Parameter::GetValueType. For example, strings have an edit control, numeric types like float and integer use a slider, and boolean parameters use a checkbox.

PPGItem AddString	(	const CString &	in_ParamName,
		const CString &	in_Label = `CString()`,
		bool	in_Multiline = `false`,
		LONG	in_Height = `120`
	)

PPGItem AddEnumControl	(	const CString &	in_ParamName,
		const CValueArray &	in_UIItemsArray,
		const CString &	in_Label = `CString()`,
		const CString &	in_UIType = `CString(L"Combo")`
	)

in_ParamName	Scripting name of the Parameter. The call does not fail even if no parameter by this name exists. However in that case the control is not drawn as part of the layout. (See PPGItem::GetName).
in_UIItemsArray	A 1-Dimensional array of Label/Value pairs. Each label is a CValue containing a CString and the value is a CValue whose type should match the Parameter::GetValueType of the associated Parameter. For example, for a bitfield, the array might contain ( L"Bit 0", 1l, L"Bit 1", 2l, L"Bit 2", 4l ).
in_Label	Most controls have a label, for example the text that appears to the left of a numeric slider. If not specified here, the value returned from SIObject::GetName or Parameter::GetScriptName is shown instead. (See PPGItem::GetLabel).
in_UIType	Specify the control to draw. A complete list of possible controls is provided in the siPPGControlType string constants, but in the case of this function only certain controls, such as ::siControlCombo, ::siControlRadio, ::siControlCheck, and ::siControlIconList are supported.

PPGItem AddColor	(	const CString &	in_RedComponentParamName,
		const CString &	in_Label = `CString()`,
		bool	in_Alpha = `false`
	)

in_RedComponentParamName	Script Name of the Parameter that represents the Red component of the color. The names of the Green, Blue and optional Alpha parameters do not need to be specified because Softimage uses the parameters that are consecutive after the Red component.
in_Label	Specify the text which appears to the left of the Color Widget. If not specified here, the value returned from SIObject::GetName or Parameter::GetScriptName appears instead. (See PPGItem::GetLabel).
in_Alpha	Specifies whether the color should include an Alpha channel. This argument decides whether a ::siControlRGBA or ::siControlRBG is created.

PPGItem AddButton	(	const CString &	in_ScriptName,
		const CString &	in_Label = `CString()`
	)

in_ScriptName	A unique name for the button, which should not contain any space characters. This name is used to determine the logic subroutine to call when the button is pressed.
in_Label	Label of the button. If not specified then the ScriptName is displayed.

PPGItem AddFCurve	(	const CString &	in_ScriptName,
		LONG	in_Height = `300`
	)

in_Text	Text to display. This can be changed afterwards by calling PPGItem::PutLabel.
in_Width	Width of the text (in pixels). If not specified, the text will use the entire width of the Property Page and will not word wrap even if it does not fit.
in_Height	Height of the text. If not specified, the text's height is calculated based on the number of lines of text.

in_Width	Width of the spacer (in pixels). It is only necessary to specify this value when there are other controls in the same row.
in_Height	Height of the text. If not specified the spacer will be a standard control height (22 pixels)

in_ScriptName	Scripting name of the Parameter, which must be of type FCurve. The call does not fail even if no parameter by this name exists. However in that case the control is not drawn as part of the layout. (See PPGItem::GetName).
in_Height	Height of the control.

PPGItem AddStaticText	(	const CString &	in_Text,
		LONG	in_Width = `0`,
		LONG	in_Height = `0`
	)

PPGItem AddSpacer	(	LONG	in_Width = `0`,
		LONG	in_Height = `0`
	)

PPGItem AddGroup	(	const CString &	in_Label = `CString()`,
		bool	in_ShowFrame = `true`,
		LONG	in_WidthPercentage = `0`
	)

in_Label	When specified, the label is shown and a frame is drawn around the group.
in_ShowFrame	Flag whether to draw a frame around the items in the control. When a label is specified a frame is always drawn (see ::siUIShowFrame).
in_WidthPercentage	This parameter is only applicable if the group is part of a row. It describes how much of the horizontal space should be taken by this group. If not specified, Softimage uses its own heuristic to lay out the group. For example, it might look better to split two groups 30%/70%, rather than using even spacing, if the second group has wider controls than the first.

in_posX	The horizontal component of the position
in_posY	The vertical component of the position

CStatus GetViewPosition	(	LONG &	out_posX,
		LONG &	out_posY
	)		const

out_posX	The horizontal component of the position
out_posY	The vertical component of the position

in_width	The width of the size
in_height	The height of the size

CStatus GetViewSize	(	LONG &	out_width,
		LONG &	out_height
	)		const

Class Description

Public Member Functions

Constructor & Destructor Documentation

Member Function Documentation

out_width	The width of the size
out_height	The height of the size

CStatus PutAttribute	(	const CString &	in_UIAttribute,
		const CValue &	in_AttributeValue
	)

in_UIAttribute	One of the siPPGLayoutAttribute string constants, specifying which attribute to set.
in_AttributeValue	CValue containing a new value for the attribute. It is possible to remove an attribute by providing an empty CValue.