CreateFirstProxyControl - cCJAction

Finds the first COM control for this menu item and creates a proxy object for it.

Type: Function
Return Data Type: Handle

Syntax

Function CreateFirstProxyControl Returns Handle

Call Example

Get CreateFirstProxyControl to HandleVariable

Description

CreateFirstProxyControl searches the commandbar system for the first COM control that has an Id (ComId) that is the same as this object's action Id (piId). If found, it creates a new DataFlex object and binds it to the COM control. The class of the newly created object will vary based on the ComType of the COM control. The proxy class used for this object will be determined by calling ClassForControlType function.

This method is needed when you need to bind a COM control to a proxy object but you do not know the control's COM dispatch pointer. If you already have the COM pointer, which is typical inside of the OnExecute and OnPopupInit events you should use the CreateProxyControl method instead.

It is the programmer's responsibility to destroy this object when they no longer need it.

Sample

The following example shows how you could get the value of an edit control's text value from another object. We have an edit object and button on the same toolbar. When the button is selected, we want to get the edit control's text value (ComText) to perform some other task.

Object oEditMenuItem is a cCJMenuItem
    Set peControlType to xtpControlEdit

    Procedure OnCreateControl Handle hoObj
        // set the initital value of the text
        Set ComText of hoObj to "test"
    End_Procedure

End_Object

Object oRunButton is a cCJMenuItem
    Set psCaption to "Run"

    Procedure OnExecute Variant vCommandBarControl
        Handle hoEdit
        String sText
        // Find the COM control that has the same action Id as the
        // oEditMenuItem's action. We assume there will only be one 
        // such control.  
        Get CreateFirstProxyControl of oEditMenuItem to hoEdit
        If (hoEdit) Begin
            Get ComText of hoEdit to sText
            Send Destroy of hoEdit
        End
        Send RequestRun sText 
    End_Procedure

End_Object

Note

In most cases, there will only be one COM control assigned to this object's action id. If end users are allowed to edit and customize their menus and toolbars it is possible that there can be multiple controls assigned to the same action. The term "first" has no defined meaning and you should not count on any kind of ordering of multiple controls. If you might have multiple controls assigned to a single action, you can use the FindAllControls function, which returns an array of COM pointers to the matching controls. You would then have to bind each of these controls using CreateProxyControl.

This function will be used most often with the complex menu item controls such as combos and edits. See cCJCommandbarComboBox and cCJCommandbarEdit for more samples.

Return Value

Returns handle to newly created proxy object bound to the COM control. Returns zero if an error occurred.