PPGItem Class Reference
#include <xsi_ppgitem.h>
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.
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 ) ;
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 ) ;
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 |
| PPGItem | ( | ) |
Default constructor.
| ~PPGItem | ( | ) |
Default destructor.
| bool IsA | ( | siClassID | in_ClassID | ) | const [virtual] |
Returns true if a given class type is compatible with this API class.
| in_ClassID | class type. |
Reimplemented from CBase.
| siClassID GetClassID | ( | ) | const [virtual] |
Creates an object from another object.
| in_obj | constant class object. |
Creates an object from a reference object. The newly created object is set to empty if the input reference object is not compatible.
| in_ref | constant class 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).
Sets the name of the item.
| in_Name | The control item's name |
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)
| in_Label | The control's label text |
| CString GetType | ( | ) | const |
Returns the control type to display on the Property Page.
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.
| in_Type | CString containing one of the siPPGControlType string constants |
| 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.
| 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).
| in_items | CValueArray containing a label and value for each item |
| LONG GetWidthPercentage | ( | ) | const |
Returns the WidthPercentage.
| 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.
| in_percent | Width of the control as a percentage of the total width of the property page |
| LONG GetLabelPercentage | ( | ) | const |
Returns the width of the label of a control, in terms of its percentage of the control's total width.
| 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.
| in_percent | Width of the control's label |
| LONG GetLabelMinPixels | ( | ) | const |
Returns the minimum width, in pixels, to use when drawing a label.
| 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
| in_pixels | Minimum width for the label |
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.
| 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. |
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.
| in_UIAttribute | CString specifying which attribute to get. The siPPGItemAttribute string constant provides a complete list of supported attributes. |
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() ) ;