# PPGItem Class Reference

Related Scripting Object: PPGItem

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

`#include <xsi_ppgitem.h>`

Inheritance diagram for PPGItem:

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

## 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, 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 ) ;

## 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, 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, 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, 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, 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, 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, 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, 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, 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, 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, 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, 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, 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, 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:

- xsi_ppgitem.h