OnExecute - cCJAction

Event that is called when an action (a menu item or toolbar item) is executed

Type: Event

Parameters: Variant vCommandBarControl

Parameter Description
vCommandBarControl Pointer to the COM control that was executed. If used, this must be bound to a DataFlex proxy object, which should be based cCJCommandBarControl or one if its sub-classes. This is rarely needed.

Parameter	Description
vCommandBarControl	Pointer to the COM control that was executed. If used, this must be bound to a DataFlex proxy object, which should be based cCJCommandBarControl or one if its sub-classes. This is rarely needed.

Syntax

Procedure OnExecute Variant vCommandBarControl

Description

OnExecute is called when you select an item by either clicking on a menu/toolbar item or by selecting a menu item and pressing enter. The OnExecute procedure is where you will write your code to make an action do whatever you want it to do.

Procedure OnExecute Variant vCommandBarControl
    Handle hoClient
    Get Client_Id to hoClient
    Send Activate_oItemsPerOrderWP of hoClient
End_Procedure

OnExecute and OnPopupInit

OnExecute is called when your menu or toolbar item is a non-popup item. If your menu or toolbar item is a popup item, the OnPopupInit event is sent instead. A item's type is controlled by the control's peControlType property.

The Execute Process

When an item is executed, it sends the Execute message to the action object. Execute first verifies that that action's item is enabled by calling IsEnabled. If it is not enabled, it returns and does nothing. If it is enabled, it calls OnExecute. It then sends Update, which will reset pbEnabled, pbChecked and pbVisible as needed. As long as you place the code within IsEnabled that checks if it is appropriate to execute a menu item for a particular focused object, you never have to worry about adding code to OnExecute to check for this. Also, as long as you place all code required to determine an action's checked, enabled and visible state within the IsChecked, IsEnabled and IsVisible functions, any changes in an item's state will be updated automatically at the end of the execute process.

For example this sub-class will never receive OnExecute unless the focus object is a proper type of object (a DEO) in a proper state (there is something to save).

Class cCJSaveMenuItem is a cCJDeoMenuItem
    
    Procedure Construct_Object
        Forward Send Construct_Object
        Set psCaption   to C_$CaptionSave
        Set psToolTip to C_$ToolTipSave
        Set psDescription to C_$DescSave
        Set psImage to "ActionSaveRecord.ico"
        Set psShortcut to "F2"
    End_Procedure

    Procedure OnExecute Variant vCommandBarControl
        Send Request_save of (focus(Self))
    End_Procedure

    Function IsEnabled Returns Boolean
        Boolean bIsDEO bHasRecord bChanged bEnabled bHasIndex
        Handle hoServer
        Get DEOInformation (&hoServer) (&bHasRecord) (&bChanged) (&bHasIndex) to bIsDeo
        Function_Return (bIsDEO and hoServer and bChanged)
    End_Function
         
End_Class

Checkboxes

You can use OnExecute to change the checked state of an item. Although you can do this by changing the pbChecked state of the item, you are encouraged to set the checked state by setting the checked state of some property outside of this object (which you will probably need to do anyway) and then adding code to IsChecked to update the item.

Object oTabWorkSpaceMenu is a cCJMenuItem
    Set psCaption to "&Tab Workspace"
    Set psToolTip to "Tab Workspace"
    Set psDescription to  "Add or Remove the tab workspace"

    Procedure OnExecute Variant vCommandBarControl
         Handle hoCommandBar
        // assume this toggles an external property called pbTabWorkspace and that it
        // does whatever needs to be done to your application to reflect this change
        Get CommandBarSystemObject to hoCommandBar
        Send ToggleTabWorkspace of hoCommandBar
    End_Procedure

     Function IsChecked Returns Boolean
        Boolean bOn
        Get pbTabWorkspace to bOn
        Function_Return bOn
     End_Function

End_Object

Directing an OnExecute message

The message you send in an OnExecute message will often be sent to one of two locations:

1. The Focus object

2. The commandbar system object or its parent via delegation

A message is sent to the focus object by sending it to (Focus(self)). You should use IsEnabled to make sure the focus object is an appropriate destination of the message.

    Procedure OnExecute Variant vCommandBarControl
        Send DoSave of (focus(Self))
    End_Procedure

A message is sent to the commandbar system object by sending it to the handled returned by the CommandBarSystemObject function. This method is preferred to allowing the message to just delegate to the commandbar system, as this approach will work with context menus, which can be located anywhere within your application. The CommandBarSystemObject function will work anywhere.

    Procedure OnExecute Variant vCommandBarControl
        Handle hoCommandBar
        Get CommandBarSystemObject to hoCommandBar
        Send DoSave of hoCommandBar
    End_Procedure

The vCommandBarControl Parameter

The parameter passed is a pointer to the COM control that was executed. Normally you will not need to do anything with this object. The object is already bound to the COM action and the action interface provides most of the information you need to manage this event. The action interface consists of properties and methods that are common to all menu and tool bar items (e.g. psCaption, pbActiveUpdate, pbChecked). In some cases, the control itself will contain information that you need to obtain or change. If this happens you will need to create an object for this control, bind the COM pointer to this object, operate on the object, and then destroy it. This is done as follows:

Procedure OnExecute Variant vCommandBarControl
    Handle hoObj

    // create the proxy object
    Get Create U_cCJCommandBarComboBox to hoObj
    
    // bind it
    Set pvComObject of hoObj to vCommandBarControl
    :
    // do whatever you need to do with the control
    :
    // destroy the of object
    Send Destroy of hoObj 

    :    
End_Procedure

Depending on the type of your control you will need to create objects based on different COM objects (e.g. cCJCommandBarControl, cCJCommandBarComboBox, cCJCommandBarButton). The function CreateProxyControl was created to make it easier to create and bind a proxy control. It will create a bound object based on the best control type for the passed control. This simplifies the above example as follows:

Procedure OnExecute Variant vCommandBarControl
    Handle hoObj

    // create and bind the proxy object
    Get CreateProxyControl vCommandBarControl to hoCombo

    :
    // do whatever you need to do with the control
    :
    // destroy the object
    Send Destroy of hoObj 

    :    
End_Procedure

OnExecute and Combo Controls

The above technique will most often be required when working with combo controls. The following example shows how a combo control could be used to activate views:

Object oViewsToolItem is a cCJMenuItem
    
    Set peControlType to xtpControlComboBox
    
    Procedure OnCreateControl Handle hoCombo
        Send FillComboList hoCombo
    End_Procedure
    
    // when used with combo forms, the control is passed 
    Procedure OnPopupInit Variant vCommandBarControl Handle hoCommandBarControls
        Handle hoCombo
        Get CreateProxyControl vCommandBarControl to hoCombo
        Send FillComboList hoCombo
        Send Destroy of hoCombo
    End_Procedure
    
    Procedure FillComboList Handle hoCombo
        Send ComClear     of hoCombo
        Send ComAddItem   of hoCombo "Order" 1
        Set  ComItemData  of hoCombo 1 to msg_Activate_oOrderEntryView
        Send ComAddItem   of hoCombo "Customer" 2
        Set  ComItemData  of hoCombo 2 to msg_Activate_oCustomerView
        Send ComAddItem   of hoCombo "Vendor" 3
        Set  ComItemData  of hoCombo 3 to msg_Activate_oVendorView
        Send ComAddItem   of hoCombo "Inventory" 4
        Set  ComItemData  of hoCombo 4 to msg_Activate_oInventoryView
        Send ComAddItem   of hoCombo "Sales Person" 5
        Set  ComItemData  of hoCombo 5 to msg_Activate_oSalesPersonView
    End_Procedure
        
    Procedure OnExecute Variant vCommandBarControl
        Handle hMessage hoClient hoCombo
        Integer iIndex
        Get CreateProxyControl vCommandBarControlto hoCombo
        Get ComListIndex of hoCombo to iIndex
        If (iIndex>0) Begin
            Get ComItemData of hoCombo iIndex to hMessage
            If hMessage Begin
                Get Client_Id to hoClient
                Send hMessage to hoClient        
            End
        End
        Send destroy of hoCombo
    End_Procedure
    
End_Object

See cCJCommandBarComboBox and cCJMenuItem for more about using combo controls.

Note

It is possible that vCommandBarControl will be null. This should be checked with IsNullComObject(). If the value is null, the programmer might have sent the Execute method within their code.