This callback is fired when a user interacts with a property page.
Use this callback to handle user interface events on a property page. The callback is fired when a user:
The callback may also be triggered by scripting code that opens the property page or changes a parameter value.
| Warning | This callback is available in the object model for C# only. For scripting, there is a separate callback for each PPG event in the object model. The scripting callbacks have no input arguments, instead the global PPG object is used to access to the controls and layout of the property page. |
C++ and C# Custom Properties
public class <property_name>
{
public bool PPGEvent( Context in_context )
{
...
}
} |
CStatus <property_name>_PPGEvent( CRef& in_context )
{
...
} |
<property_name> is the name specified in the call to PluginRegistrar.RegisterProperty, with any spaces converted to underscores. For example, if you register a property with the name "My Property", the callback function names start with "My_Property".
| Parameter | Language | Type | Description |
|---|---|---|---|
| in_context | C# | PPGEventContext | The PPGEventContext object. PPGEventContext.EventID identifies the event that triggered the callback. For the siOnInit, siOnClose, siTabChange, and siButtonClicked events, PPGEventContext.Source returns the CustomProperty. For siParameterChange events, PPGEventContext.Source returns the Parameter object. You can get the CustomProperty by calling the SIObject.Parent property on the Parameter. |
| C++ | CRef& | A reference to a PPGEventContext. PPGEventContext::GetEventID identifies the event that triggered the callback. For the siOnInit, siOnClose, siTabChange, and siButtonClicked events, PPGEventContext::GetSource returns the CustomProperty. For siParameterChange events, PPGEventContext::GetSource returns the Parameter object. You can get the CustomProperty from Parameter::GetParent. |
| Attribute | Description |
|---|---|
| Button | For a siButtonClicked event, specifies the name of the button that was clicked. |
| Close | Set to true to force Softimage to close the property page. |
| Refresh | Set to true to force Softimage to update the layout of the property page. |
| Tab | For a siTabChange event, specifies the name of the tab that was clicked. |
// PPGEvent callback generated by the Custom Property Wizard
SICALLBACK MyCppProperty_PPGEvent( const CRef& in_ctxt )
{
// This callback is called when events happen in the user interface
// This is where you implement the "logic" code.
// If the value of a parameter changes but the UI is not shown then this
// code will not execute. Also this code is not re-entrant, so any changes
// to parameters inside this code will not result in further calls to this function
Application app ;
// The context object is used to determine exactly what happened
// We don't use the same "PPG" object that is used from Script-based logic code
// but through the C++ API we can achieve exactly the same functionality.
PPGEventContext ctxt( in_ctxt ) ;
PPGEventContext::PPGEvent eventID = ctxt.GetEventID() ;
if ( eventID == PPGEventContext::siOnInit )
{
// This event meant that the UI was just created.
// It gives us a chance to set some parameter values.
// We could even change the layout completely at this point.
// For this event Source() of the event is the CustomProperty object
CustomProperty prop = ctxt.GetSource() ;
app.LogMessage( L"OnInit called for " + prop.GetFullName() ) ;
/* If you regenerate the layout then call this:
ctxt.PutAttribute(L"Refresh",true);
*/
}
else if ( eventID == PPGEventContext::siOnClose )
{
// This event meant that the UI was just closed by the user.
// For this event Source() of the event is the CustomProperty object
CustomProperty prop = ctxt.GetSource() ;
app.LogMessage( L"OnClose called for " + prop.GetFullName() ) ;
}
else if ( eventID == PPGEventContext::siButtonClicked )
{
// If there are multiple buttons
// we can use this attribute to figure out which one was clicked.
CValue buttonPressed = ctxt.GetAttribute( L"Button" ) ;
app.LogMessage( L"Button pressed: " + buttonPressed.GetAsText() ) ;
}
else if ( eventID == PPGEventContext::siTabChange )
{
// We will be called when the PPG is first opened
// and every time the tab changes
// Retrieve the label of the tab that is now active
CValue tabLabel = ctxt.GetAttribute( L"Tab" ) ;
app.LogMessage( L"Tab changed to: " + tabLabel .GetAsText() ) ;
}
else if ( eventID == PPGEventContext::siParameterChange )
{
// For this event the Source of the event is the parameter
// itself
Parameter changed = ctxt.GetSource() ;
CustomProperty prop = changed.GetParent() ;
CString paramName = changed.GetScriptName() ;
app.LogMessage( L"Parameter Changed: " + paramName ) ;
}
return CStatus::OK ;
} |