Extend a child table using events

Contents

• Overview
• Process an event
• Event Arguments
• Handled
• Return
• Example

Overview

This page describes the usage of the event model to extend an instance of cChildTable. In Centura a child table instance could be extended by adding methods directly onto the instance in design time. In practice this is the equivalent of creating a subclass of cChildTable on which methods are added. In C# this is not possible and even quite simple actions like overriding the DataSourcePopulateIt method requires that a new child table class is declared. To minimize the need to subclass cChildTable, there are published events for the public virtual methods through which the application developer can achieve the same result.

Process an event

Open a designer and select the child table. In the property dialog select the Events view. The category F1 Late Bind Events contains an event for each public virtual method of a child table. To extend the functionality of a child table instance simply subscribe to any of the events and implement the logic.

Figure 1: Properties view with F1 Late Bind Events

You subscribe to and handle these events in the same way as you would for any other .NET standard event. Subscribing can be done in two ways. Double click the event in the property dialog and a event handler will be generated for you. The other way is to write the event handler up front and then connect the event handler to the event in the property dialog by selecting it from the drop down list. For more information about handling events please see MSDN.

Event Arguments

The event handlers for the late bind events are called with event arguments. The event arguments contain the same arguments that the corresponding virtual method does. For detailed information about parameters and their usage, please see the cChildTable API documentation for the corresponding method. All the specialized event argument classes derive from the FndReturnEventArgs class.

Handled

Besides the standard method parameters, the event argument class also contains a property Handled. This property is used to inform the method that raised the event if the implementation did call the base method or not. If this property is not set or set to false, then the framework will call the base implementation when the event handler returns. If the property is set to true then the framework will not call the base implementation.

You should set the Handled property if

• The added logic depends on the base implementation, and the base method is called by your code
• You want to replace the base logic completely.

Otherwise, just add your logic and exit the handler and let the framework call the base method.

Return

Each specialized event arguments class derives from the FndReturnEventArgs class. This class declares the event return type. Every event has a return type, but it is not always used. See the documentation for the event you are going to use for a specification on how to use the return property.

To return from the event handler you should set the ReturnValue property of the supplied EventArgs class. The event handler callback method itself is declared as void and does not support any return values.

Example

 In Figure 1, DataSourcePopulateItEvent for a child table is received to add calculation logic when the table has finished populating. In this case we let the base logic populate the table, verifies the result of populating and then call our calculation logic.

private void tblItems_DataSourcePopulateItEvent(object sender, cDataSource.DataSourcePopulateItEventArgs e)
{
    e.Handled = true;
    e.ReturnValue = tblItems.DataSourcePopulateIt(e.nParam);

    // If table populated OK we calculate column sums
    if (e.ReturnValue == true)
    {
        CalculateColumnSum();
    }
}

Figure 1: Example showing the use of events for child table.