Public Member Functions
PPGItem Class Reference

Detailed Description

This object represents a component of the user interface of a Property Page.

Normally a PPGItem represents a user interface control that is directly related to a Parameter of the object that is inspected. For example a PPGItem of type ::siControlString would display the value of a string parameter. Similarly a PPGItem of type ::siControlFCurve would show the FCurve contained inside a FCurve Parameter. The connection between the control and its associated Parameter is established based on the the PPGItem's Name (see PPGItem::GetName).

Some PPGItems do not directly correspond to a parameter, for example Buttons, Tabs and Groups.

Each PPGItem exposes a series of attributes that can be used to tweak its appearance. Some of the most common attributes are exposed directly as properties of the object, for example PPGItem::GetLabel, whereas the more specialized or uncommon attributes can be accessed via PPGItem::GetAttribute.

PPGItem objects are accessible via the PPGLayout of a ProjectItem.

See also:
ProjectItem::GetPPGLayout, PPGLayout::AddItem, PPGLayout::GetItem, cus_ppg_PropertyPageControls Property Page Controls
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 ;
        oPSet.AddParameter( L"Check1", CValue::siBool, siPersistable, L"", L"", CValue(), param ) ;
        oPSet.AddParameter( L"Check2", CValue::siBool, siPersistable, L"", L"", CValue(), param ) ;

        PPGLayout oPPGLayout = oPSet.GetPPGLayout() ;
        oPPGLayout.AddGroup( L"", true ) ;
        oPPGLayout.AddRow() ;
        oPPGLayout.AddItem( L"Check1" ) ;

        PPGItem oItem = oPPGLayout.AddItem( L"Check2" ) ;
        oItem.PutLabel( L"Check box 2" ) ;

        oPPGLayout.EndRow() ;
        oPPGLayout.EndGroup() ;

        //We can look up and change the items afterwards
        oItem = oPPGLayout.GetItem( L"Check1" ) ;
        oItem.PutLabel( L"Check Box 1" ) ;

        //Show our PPG
        CValueArray args(5) ;
        args[0] = oPSet ;

        CValue retval = false ;
        app.ExecuteCommand( L"InspectObj", args, retval ) ;
Example:
Shows a property page with controls for picking files and folders. This sort of UI is often used in import/export plug-ins. 
        using namespace XSI;
        Application app;
        Model root = app.GetActiveSceneRoot();

        CustomProperty oPSet ;
        root.AddProperty( L"CustomProperty", false, L"Demo", oPSet) ;

        Parameter param ;
        oPSet.AddParameter( L"ExportFile", CValue::siString, siPersistable, L"", L"", CValue(), param ) ;
        oPSet.AddParameter( L"ImportFile", CValue::siString, siPersistable, L"", L"", CValue(), param ) ;
        oPSet.AddParameter( L"FolderPicker", CValue::siString, siPersistable, L"", L"", CValue(), param ) ;

        PPGLayout oPPGLayout = oPSet.GetPPGLayout() ;
        PPGItem oItem = oPPGLayout.AddItem( L"ExportFile", L"Export Filename", siControlFilePath ) ;

        // You can use the string directly, or the typdef siUIInitialDir (one of the siPPGItemAttribute string constants)
        oItem.PutAttribute( L"initialdir", L"project" ) ;
        oItem.PutAttribute( siUIFileFilter, L"Text files (*.txt)|*.txt|All Files (*.*)|*.*||" ) ;

        oItem = oPPGLayout.AddItem( L"ImportFile", L"", siControlFilePath ) ;

        oItem.PutAttribute( siUIFileFilter, L"xsiaddon files (*.xsiaddon)|*.xsiaddon|"
                                            L"spdl files (*.spdl)|*.spdl|"
                                            L"All Files (*.*)|*.*||" ) ;
        oItem.PutAttribute( siUIOpenFile, true ) ;
        oItem.PutAttribute( siUIFileMustExist, true ) ;

        oPPGLayout.AddItem( L"FolderPicker", L"", siControlFolder ) ;

        CValueArray args(5) ;
        args[0] = oPSet ;
        CValue retval = false ;
        app.ExecuteCommand( L"InspectObj", args, retval ) ;

#include <xsi_ppgitem.h>

Inheritance diagram for PPGItem:
Inheritance graph
[legend]

List of all members.

Public Member Functions
  PPGItem ()
  ~PPGItem ()
  PPGItem (const CRef &in_ref)
  PPGItem (const PPGItem &in_obj)
bool  IsA (siClassID in_ClassID) const
siClassID  GetClassID () const
PPGItem &  operator= (const PPGItem &in_obj)
PPGItem &  operator= (const CRef &in_ref)
CString  GetName () const
CStatus  PutName (const CString &in_Name)
CString  GetLabel () const
CStatus  PutLabel (const CString &in_Label)
CString  GetType () const
CStatus  PutType (const CString &in_Type)
CValueArray  GetUIItems () const
CStatus  PutUIItems (const CValueArray &in_items)
LONG  GetWidthPercentage () const
CStatus  PutWidthPercentage (LONG in_percent)
LONG  GetLabelPercentage () const
CStatus  PutLabelPercentage (LONG in_percent)
LONG  GetLabelMinPixels () const
CStatus  PutLabelMinPixels (LONG in_pixels)
CStatus  PutAttribute (const CString &in_UIAttribute, const CValue &in_AttributeValue)
CValue  GetAttribute (const CString &in_UIAttribute) const

Constructor & Destructor Documentation

PPGItem ( )

Default constructor.

~PPGItem ( )

Default destructor.

PPGItem ( const CRef &  in_ref )

Constructor.

Parameters:
in_ref constant reference object.
PPGItem ( const PPGItem &  in_obj )

Copy constructor.

Parameters:
in_obj constant class object.

Member Function Documentation

bool IsA ( siClassID  in_ClassID ) const [virtual]

Returns true if a given class type is compatible with this API class.

Parameters:
in_ClassID class type.
Returns:
true if the class is compatible, false otherwise.

Reimplemented from CBase.

siClassID GetClassID ( ) const [virtual]

Returns the type of the API class.

Returns:
The class type.

Implements CBase.

PPGItem& operator= ( const PPGItem &  in_obj )

Creates an object from another object.

Parameters:
in_obj constant class object.
Returns:
The new PPGItem object.
PPGItem& operator= ( const CRef &  in_ref )

Creates an object from a reference object. The newly created object is set to empty if the input reference object is not compatible.

Parameters:
in_ref constant class object.
Returns:
The new PPGItem object.
CString GetName ( ) const

Returns the name of the item. For most controls the name matches the script name of the parameter that is inspected by the control (see Parameter::GetScriptName). For ::siControlRGBA this is the name of the parameter that represents the Red Component of the color (see PPGLayout::AddColor).

Returns:
The control item's name
See also:
PPGItem::PutName, PPGItem::GetLabel, Parameter::GetScriptName, ProjectItem::GetPPGLayout
CStatus PutName ( const CString &  in_Name )

Sets the name of the item.

Parameters:
in_Name The control item's name
See also:
PPGItem::GetName, Parameter::GetScriptName, ProjectItem::GetPPGLayout
CString GetLabel ( ) const

Returns the label of the PPGItem.

Returns:
The control's label text
See also:
PPGItem::PutLabel, PPGItem::GetName, Parameter::GetScriptName, PPGLayout::AddItem
CStatus PutLabel ( const CString &  in_Label )

Returns the label of the PPGItem. For many controls this text appears to the left of the control. When not specified the name of the parameter (see SIObject::GetName and or Parameter::GetScriptName) is displayed.

For convenience methods like PPGLayout::AddItem allow you to specify the label without an extra call to this method.

This attribute is optional for Groups and Buttons and mandatory for Tabs. See PPGLayout::AddGroup, PPGLayout::AddButton and PPGLayout::AddTab.

To draw a control without any label use the siUINoLabel or siUIValueOnly flags. (See ::siPPGItemAttribute)

Parameters:
in_Label The control's label text
See also:
PPGItem::GetLabel, PPGItem::GetName, Parameter::GetScriptName, PPGLayout::AddItem, cus_ppg_Labels Labels
CString GetType ( ) const

Returns the control type to display on the Property Page.

Returns:
String containing one of the siPPGControlType strings.
See also:
PPGItem::PutType, cus_ppg_PropertyPageControls Property Page Controls
CStatus PutType ( const CString &  in_Type )

Sets the control type to display on the Property Page. This property is optional: when not set, Softimage picks a control based on the type of the parameter (see Parameter::GetValueType). For example, a siDouble uses a ::siControlNumber.

Parameters:
in_Type CString containing one of the siPPGControlType string constants
See also:
PPGLayout::AddItem, cus_ppg_PropertyPageControls Property Page Controls
CValueArray GetUIItems ( ) const

Returns the list of items and values associated with a control. This property is used by controls which display items from a fixed list of choices, for example ::siControlCombo, ::siControlCheck, ::siControlRadio, and ::siControlIconList.

Returns:
CValueArray containing the label/value pairs
See also:
PPGLayout::AddEnumControl, PPGItem::PutUIItems, cus_ppg_EnumControls Enum Controls
CStatus PutUIItems ( const CValueArray &  in_items )

Sets the list of items and values associated with a control as a 1-dimensional array of Label/Value pairs. This property is used by controls which display items from a fixed list of choices, for example ::siControlCombo, ::siControlCheck, ::siControlRadio, and ::siControlIconList. Each label is a string and the value is a CValue whose type should match the type of the associated parameter (see Parameter::GetValueType).

Parameters:
in_items CValueArray containing a label and value for each item
See also:
PPGLayout::AddEnumControl, PPGItem::GetUIItems, cus_ppg_EnumControls Enum Controls
LONG GetWidthPercentage ( ) const

Returns the WidthPercentage.

Returns:
Width of the control as a percentage of the total width of the property page
See also:
PPGItem::PutWidthPercentage, cus_ppg_SettingControlAttributes Setting Control Attributes
CStatus PutWidthPercentage ( LONG  in_percent )

Returns the WidthPercentage. This property is only applicable if the group is part of a row. It gives a hint to Softimage about how much of the horizontal space should be taken by this item. If not specified, Softimage uses its own heuristic to lay out the row.

Parameters:
in_percent Width of the control as a percentage of the total width of the property page
See also:
PPGLayout::AddGroup, PPGItem::GetWidthPercentage, cus_ppg_SettingControlAttributes Setting Control Attributes
LONG GetLabelPercentage ( ) const

Returns the width of the label of a control, in terms of its percentage of the control's total width.

Returns:
Width of the control's label
See also:
PPGItem::GetLabelMinPixels, PPGItem::GetWidthPercentage, PPGItem::GetAttribute, cus_ppg_SettingControlAttributes Setting Control Attributes
CStatus PutLabelPercentage ( LONG  in_percent )

Sets the width of the label of a control, in terms of its percentage of the control's total width. When not set, Softimage will use its own heuristic, but this can be useful to give a hint when tweaking the layout. For example this can be useful to force a LONG label onto multiple lines rather than squish the controls.

To completely hide a label use the ::siUINoLabel or ::siValueOnly UI Attribute (see siPPGItemAttribute).

This function should always be used in conjunction with PPGItem::PutLabelMinPixels.

Parameters:
in_percent Width of the control's label
See also:
PPGItem::GetLabelPercentage, PPGItem::PutLabelMinPixels, PPGItem::PutWidthPercentage, PPGItem::PutAttribute, cus_ppg_SettingControlAttributes Setting Control Attributes
LONG GetLabelMinPixels ( ) const

Returns the minimum width, in pixels, to use when drawing a label.

Returns:
Minimum width for the label
See also:
PPGItem::GetLabelPercentage, PPGItem::PutLabelMinPixels, PPGItem::GetAttribute, cus_ppg_SettingControlAttributes Setting Control Attributes
CStatus PutLabelMinPixels ( LONG  in_pixels )

Sets the minimum width, in pixels, to use when drawing a label. A label will get split into multiple lines when there is not enough space on a single line.

This function should always be used in conjunction with PPGItem::PutLabelPercentage

Parameters:
in_pixels Minimum width for the label
See also:
PPGItem::PutLabelPercentage, PPGItem::GetLabelMinPixels, PPGItem::PutAttribute, cus_ppg_SettingControlAttributes Setting Control Attributes
CStatus PutAttribute ( const CString &  in_UIAttribute,
const CValue &  in_AttributeValue 
)

Sets an attribute on the control. Each control has a collection of attributes which can be used to tweak its appearance or to provide it with additional states. Some of these attributes are general and apply to almost any control, for example ::siUIAlignCenter. Others are specific to the control, for example ::siUINoSlider (which only applies to numeric controls).

If the attribute argument is not a recognized attribute this method fails. It is possible to remove an attribute by calling this method with an empty CValue as the AttributeValue argument.

For convenience, some of the most common attributes have been exposed directly as properties, for example PPGItem::PutLabel and PPGItem::PutUIItems.

Parameters:
in_UIAttribute CString specifying which attribute to set. The siPPGItemAttribute string constant provides a complete list of supported attributes.
in_AttributeValue CValue with the new value for the attribute.
See also:
PPGItem::GetAttribute, PPGLayout::GetAttribute, cus_ppg_SettingControlAttributes Setting Control Attributes
CValue GetAttribute ( const CString &  in_UIAttribute ) const

Returns an attribute on the control. Each control has a collection of attributes which can be used to tweak its appearance or to provide it with additional states. Some of these attributes are general and apply to almost any control, for example ::siUIAlignCenter. Others are specific to the control, for example ::siUINoSlider (which only applies to numeric controls).

If the attribute argument is not a recognized attribute the call to read it fails. Most of the attributes are optional and Softimage returns an empty CValue if the attribute has not been set.

For convenience, some of the most common attributes have been exposed directly as properties, for example PPGItem::GetLabel and PPGItem::GetUIItems.

Parameters:
in_UIAttribute CString specifying which attribute to get. The siPPGItemAttribute string constant provides a complete list of supported attributes.
Returns:
CValue containing the attribute value. An empty CValue is returned if the attribute has not been set.
See also:
PPGItem::GetAttribute, PPGLayout::GetAttribute, cus_ppg_SettingControlAttributes Setting Control Attributes
Example:
        using namespace XSI;
        Application app;
        Model root = app.GetActiveSceneRoot();

        // Create a simple pset with two string parameters
        CustomProperty oPSet ;
        root.AddProperty( L"CustomProperty", false, L"Demo", oPSet) ;

        Parameter oParam ;
        oPSet.AddParameter( L"P1", CValue::siString,
                            siPersistable, L"", L"", CValue(), oParam ) ;
        oPSet.AddParameter( L"P2", CValue::siString,
                            siPersistable, L"", L"", CValue(), oParam ) ;

        // Set out the layout.  We don't need to set any attributes
        // because of convenience arguments in AddItem and AddString

        PPGLayout oLayout = oPSet.GetPPGLayout();
        oLayout.AddItem( L"P1", L"P1 Label", siControlString ) ;
        oLayout.AddString( L"P2", L"P2 Label", true, 400 ) ;

        // Look under the hood at some of the attributes that were set
        // by the above calls

        PPGItem oItem1 = oLayout.GetItem( L"P1" ) ;
        app.LogMessage( L"P1-Attribute:Label        Value:" +
                        oItem1.GetAttribute( siUILabel ).GetAsText() ) ;
        app.LogMessage( L"P1-Attribute:Type         Value:" +
                        oItem1.GetAttribute( siUIType ).GetAsText() ) ;

        // Label and Type can also be read via the convenient methods
        app.LogMessage( L"P1-GetLabel               Value:" + oItem1.GetLabel() ) ;
        app.LogMessage( L"P1-GetType                Value:" + oItem1.GetType() ) ;

        // When we use AddString we get some other interesting attributes automatically
        // set for us
        PPGItem oItem2 = oLayout.GetItem( L"P2" ) ;
        app.LogMessage( L"P2-Attribute:Label        Value:" +
                        oItem2.GetAttribute( siUILabel ).GetAsText() ) ;

        // Type on a multi-line is "edit" instead of the "string" control
        // used on normal single line strings.
        app.LogMessage( L"P2-Attribute:Type         Value:" +
                        oItem2.GetAttribute( siUIType ).GetAsText() ) ;
        app.LogMessage( L"P2-Attribute:CY(height)   Value:" +
                        oItem2.GetAttribute( siUICY ).GetAsText() ) ;

        // This is a low-level attribute containing the specific window style
        // In most cases you would never need to read or set this value
        app.LogMessage( L"P2-Attribute:Style        Value:" +
                        oItem2.GetAttribute( siUIStyle ).GetAsText() ) ;
The documentation for this class was generated from the following file:
Generated on Fri Nov 11 2011 18:38:18 by doxygen 1.7.4
Please send us your comment about this page