<     > 

PPGEvent

This callback is used only by C++ and C# custom properties.

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.

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

// C#
public class <property_name>
{
   public bool PPGEvent( Context in_ctxt )
   {
       ...
   }
}

// C++
CStatus <property_name>_PPGEvent(  CRef& in_context )
{
   ...
}

<property_name> is the name specified in the call to RegisterProperty (see PluginRegistrar ), with any spaces removed. For example, if you register a property with the name "My Property", the callback function names start with "MyProperty".

Parameters

Context Attributes

Example

// PPGEvent callback generated by the Custom Property Wizard

XSIPLUGINCALLBACK CStatus 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::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 ;
}

See Also

• Define

• DefineLayout

• Property Callbacks

• OnChanged

• OnClicked

• OnInit

• OnTab

• Examples Installed with XSI

SOFTIMAGE|XSI v6.01     <     >