3D PLM PPR Hub Open Gateway

Knowledge Modeler

Subscribing to Events

How to be warned when events occur on parameters

Use Case

Abstract

An event is an object that notifies another that an event has occurred. This article explains how to subscribe to the events supported by the KnowledgeInterfaces framework.


What You Will Learn With This Use Case

This article explains how to subscribe to "change value", "change visu" and "delete" events.

[Top]

About the KnowledgeInterfaces Framework Events

The LiteralFeatures platform supports four types of events which are described by the CATIParrnEvents interface. These events are:

  1. the parameter value modification or " ChangeValue" event (CATIParmEvents::GetChangeValueNotification)
  2. the parameter rename (CATIParmEvents::GetRenameNotification)
  3. the modification of the parameter appearance or "Change Visu" event (CATIParmEvents::GetChangeVisuNotification)
  4. the parameter delete (CATIParmEvents::GetDeleteNotification).

When designing a literal-based application, if you want to be warned whenever a parameter is modified, you must: be provided with a feature whose purpose is to observe or detect the parameter modifications. This feature must subscribe to the events supported by the LiteralFeatures platform.

[Top]

The CAALifEvents Use Case

CAALifEvents is a use case of the CAALiteralFeatures.edu framework that illustrates KnowledgeInterfaces framework capabilities.

[Top]

What Does CAALifEvents Do

This use case:

  1. Creates a length type parameter
  2. Subscribes to the events occurring on this parameter
  3. Modifies its value
  4. Checks that a "change value" notification has been issued
  5. Modifies its access rights
  6. Checks that a "visu notification" has been issued
  7. Deletes the parameter
  8. Checks that a "delete notification" has been issued

[Top]

How to Launch CAALifEvents

To launch CAALifEvents, you will need to set up the build time environment, then compile CAALifEventsMain along with its prerequisites, set up the run time environment, and then execute the use case which main program is CAALifEventsMain [1].

[Top]

Where to Find the CAALifEvents Code

The CAALifEvents use case is located in:

Windows InstallRootDirectory\CAALiteralFeatures.edu\CAALifEvents.m\
Unix InstallRootDirectory/CAALiteralFeatures.edu/CAALifEvents.m/

where InstallRootDirectory is the directory where the CAA CD-ROM is installed.

The main program related to this use case is CAALifEventsMain.

An implementation of the CAAILifMyFeatureEvents interface is defined in the CAALifMyFeatureEventsExt extension of the CAAMyFeature late type. The interface is defined in the PrivateInterfaces directory, the implementation is defined in the CAALifEvents.m module.

[Top]

Step-by-Step

Here is the step-by-step description of the program:

  1. Retrieving the Knowledge Factory
  2. Creating a Length Parameter
  3. Specifying the Current Unit of the Length Parameter
  4. Creating the "CAAMyfeature" StartUp
  5. Creating the "OBJ0" instance from the "CAAMyFeature" StartUp
  6. Subscribing to the Three Events
  7. Modifying the Length Parameter Value
  8. Displaying the Number of "change value" Notifications
  9. Modifying the Access Rights of the Length Parameter
  10. Mofifying the Current Unit of the Length Parameter
  11. Displaying the Number of "change visu" Notifications
  12. Deleting the Length Parameter
  13. Deleting the Feature Event Object

[Top]

Retrieving the Knowledge Factory

The CATICkeParmFactory is retrieved from the document container. For more information on the purpose of this factory, see [2].

[Top]

Creating a Length Parameter

A Length type parameter is created. This parameter is assigned a 1m initial value. Let's remind you that the value you pass in the argument of a CreateLength method is read as an SI unit. This also applies to other literal creation methods. The parameter which is created is the one we are going to "observe". In other words its is going to subscribe to the events managed by the KnowledgeInterfaces framework.

[Top]

Specifying the Current Unit of the Length Parameter

The current unit of the "Length" parameter is specified as the first item of the list which is displayed in the Tools->Options->Units for parameters of Length type. In our example, the first unit in the list of units for Length type parameter is the mm. Depending on your application settings, you may get a different unit when displaying a parameter value. For more information, see [3].

[Top]

Creating the "CAAMyfeature" StartUp

The "CAAMyfeature" StartUp is created. The CAAMyFeature late type is defined in the CAALifBasis.m module. The CAALifMyFeaturesEventsExt extension provides an implementation of the CAAILifMyFeatureEvents interface which is defined in the PrivateInterfaces directory.

About the CAAILifMyFeatureEvents::Observe method:
This method which is implemented in the CAALifMyFeaturesEventsExt.cpp extension uses the CATInterfaceEvents::AddSubscription method defined in the ObjectModelerBase framework.

virtual CATCallback AddSubscription( CATInterfaceEvents *eventManager,
        CATCallbackEvent event,
        CATSubscriberMethod method,
        char *interfaceID,
        CATSubscriberData data = NULL ) = 0 ;

Writing the instruction below:

spSpev->AddSubscription(spParameterEvents,
              spParameterEvents->GetChangeValueNotification(),
             (CATSubscriberMethod)&CAAILifMyFeatureEvents::IfChangeValue,
              "CAAILifMyFeatureEvents",
            (CATSubscriberData) this);

means that the parameter the Observe method is applied to calls the service defined in the third argument (IfChangeValue) when the event specified in the second argument occurs. The CAAILifMyFeatureEvents::IfChangeValue method is defined in CAALifMyFeatureEventsExp::Observe extension. It just increments a counter and displays a message in the standard output whenever the parameter value is modified.

Subscriptions to "delete" and "change visu" events are patterned on the same principle.

[Top]

Creating the "OBJ0" instance from the "CAAMyFeature" StartUp

The "OBJ0" instance is created from the "CAAMyFeature" StartUp.

[Top]

Subscribing to the Three Events

Subscribe to the three events defined in the CAAILifMyFeatureEvents::Observe method and implemented in the CAALifMyFeatureEventsExt extension. From this point, all the "change value", "change visu" and "delete" events should issue a message and increment the counters defined in the Observe method.

[Top]

Modifying the Length Parameter Value

The "Length" parameter value is replaced with 30 mm. let's remind you that when you use the CATICkeParm::ValuateStored method the value specified in the argument is the document default unit (i.e. mm for length parameters). Upon modification of the "Length" parameter, the counter which record the "change value" events increments. The statements below:

spStore->ValuateStored (30);
cout << "The p1 value is " << spLength->Show().CastToCharPtr() << endl;

display in the standard output:

Receiving ChangeValue number 1
The p1 value is 30mm

[Top]

Displaying the Number of "change value" Notifications

The number of "change value" notifications is displayed. As expected, 1 notification has been recorded.

[Top]

Modifying the Access Rights of the Length Parameter

The access rights of the "Length" parameter are modified. A "change visu" notification should be issued. The statements below:

spLength->SetUserAccess(CATICkeParm::ReadOnly);
cout << "Number of \"change visu\" notifications (1 is expected) " ;
    cout << CAALifMyFeatureEventsExt::nbchangevisu << endl;

display in the standard output:

Receiving ChangeVisu number 1
Number of "change visu" notifications (1 is expected) 1

[Top]

Mofifying the Current Unit of the Length Parameter

The current unit of the "Length" parameter is modified. A "change visu" notification should be issued. The statements below:

spMag->SetCurrentUnit ((*(spMag->Units()))[2]);
cout << "The p1 value is " << spLength->Show().CastToCharPtr() << endl;

display in the standard output:

Receiving ChangeVisu number 2
The p1 value is 0.03m

[Top]

Displaying the Number of "change visu" Notifications

The number of "change visu" notifications is displayed. As expected, 2 notifications have been recorded.

[Top]

Deleting the Length Parameter

The "Length" parameter is deleted. The statements below:

spLco->remove();
cout << "Number of \"delete\" notifications (1 is expected) " ;
cout << CAALifMyFeatureEventsExt::nbdelete << endl;

display in the standard output the following messages

Receiving Delete number 1
Number of "delete" notifications (1 is expected) 1

[Top]

Deleting the Feature Event Object

The CAAILifMyFeatureEvents object is deleted. Note that is strongly recommended to delete an event object after all objects it was intended to be applied have been deleted.

[Top]


In Short

Four types of events are supported by the LiteralFeatures platform:

  1. The parameter value modification or " ChangeValue" event
  2. The parameter rename
  3. The modification of the parameter appearance or "Change Visu" event
  4. The parameter delete.

When developing an application, subscribing to events requires a feature dedicated to the detection of parameter modifications.

[Top]


References

[1] Building and Launching a CAA V5 Use Case
[2] Getting Started with Literal Feature Programming
[3] About Units
[Top]

History

Version: 1 [Jan 2000] Document created
[Top]

Copyright © 2000, Dassault Systèmes. All rights reserved.