OnPostEntering - cCJGrid

Called when using the Post Entering grid activation approach

Type: Event
Return Data Type: Boolean

Syntax

Function OnPostEntering Returns Boolean

Description

The Codejock COM ReportControl uses different logic that the internal DataFlex controls concerning object entering. With most framework objects, an object can return a non-zero value from the Entering procedure and the object activation will be cancelled. This approach does not work well with COM objects when activated via a mouse click. The ReportControl assumes that a mouse click has given it the focus, and no mechanism is provided for refusing the focus. What this means is that the Entering or OnEntering events cannot be used to refuse the focus because, in the case of mouse navigation, it already has the focus. This is why we recommend using the more standard Windows approach of disabling objects when they should not be entered.

For various reasons, not all developers will use the Enable/Disable approach, so we have created a mechanism that works similar to the old object entering style. In this approach, the actual entering test is deferred until after the grid focus change has occurred and it is safe to change the focus. Rather than occurring in OnEntering, which is a non-cancellable event, it occurs in a cancellable post-entering event named OnPostEntering. Basically, any logic you previously had in your legacy dbGrid's Child_Entering event is moved to OnPostEntering.

Using post-entering comes with a price. There are some events that you do not want to process before post-entering has had a chance to approve the focus change and make whatever changes are needed. For example, row changes (which may attempt a save of their own), context menus and other mouse events must be ignored if they occur before post-entering. Therefore, it is wise to limit the use of post-entering to those conditions where it is really needed. This can be done dynamically by testing if post-entering is required inside of OnEntering. If required, you set the pbNeedPostEntering property instructing the grid to make a post-entering call and to ignore various events until that call is made. Your code to do that would look like this:

// attempt a header save. Return non-zero if it fails
Function OnPostEntering Returns Boolean
   Boolean bCancel
   Delegate Get Save_Header to bCancel
   Function_Return bCancel
End_Function

// augment to enable PostEntering only when needed - when there is a change
Procedure OnEntering
    Handle hoSrvr
    Boolean bChanged

    Delegate Get Server to hoSrvr    // The Header DDO.
    Get Should_Save of hoSrvr to bChanged    // Are there any current changes?
    If ( bChanged) Begin
        Set pbNeedPostEntering to True
    End
End_Procedure

Here OnEntering tests if the current entering event is a candidate for post-entering. It does this by checking for a change in the header DDO and setting pbNeedPostEntering to true. OnPostEntering can do anything, including changing the focus. If it returns non-zero, the grid should lose the focus. You can choose to explicitly change the focus or let the grid change this for you (it will move the focus to the object that had the prior focus). If you compare this code to the legacy dbGrid Child_Entering code, you will see that these are very similar. It is important that OnEntering does whatever it does without any user input (no message boxes, no popups) and without changing the focus.

Because of the OnEntering test, most of the time OnPostEntering will not get called. This is an intentional strategy. The post-entering logic is complicated and whenever possible you want to bypass it. If you use the Enable/Disable mechanism, it will never get used. If you use the post-entering mechanism, it will only get used when a change actually exists.

Our recommendation is to use the Enable/Disable approach whenever possible as it represents the best path for the future. However, the post-entering approach, if used carefully, should work well with a minimum number of side-effects and, therefore, should be a satisfactory legacy strategy.

Return Value

If it returns non-zero, the grid should lose the focus.