Scripting: PPGEvent

PPGEvent

Description

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:

Opens the property page.
Clicks a button.
Clicks the Close button (or the equivalent with a keyboard shortcut).
Changes a parameter value in a property page control (for example, by selecting an item from a list, changing the value in a field, or selecting a check box).
Clicks a tab.

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.

Applies To

C++ and C# Custom Properties

Syntax

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".

Parameters

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.

Context Attributes

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.

Example

// 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 ;
}