FindFirstControl - cCJAction

Finds the first COM control that has the same ID as this action

Type: Function
Return Data Type: Variant

Syntax

Function FindFirstControl Returns Variant

Call Example

Get FindFirstControl to VariantVariable

Description

FindFirstControl searches the commandbar system for the first control that has the same piId as the action. It returns the variant pointer to the control or, if no control is found, null.

You should rarely need to use this method. Most of the time you will know what the COM pointer is, as this is passed to the action object when various events are called (OnExecute, OnPopupInit, OnCreateControl). When you already know the control's COM pointer you can create a proxy object to access this control by calling CreateProxyControl. Even if you don't have control's handle, you may use the higher level CreateFirstProxyControl method, which will find the control and bind a proxy object to it.

This sample shows how you use FindFirstControl to find the control and bind it to a proxy object.

Get FindFirstControl of oEditMenuItem to vEdit
If (Not(IsNullObject(vEdit))) Begin
    Get CreateProxyControl of oEditMenuItem vEdit to hoEdit
    If hoEdit Begin
        Get ComText of hoEdit to sText
        Send destroy of hoEdit
    End
End

This sample shows how you can do this more easily using CreateFirstProxyControl.

Get CreateFirstProxyControl of oEditMenuItem to hoEdit
If hoEdit Begin
    Get ComText of hoEdit to sText
    Send destroy of hoEdit
End

In most cases, this control will be the only control that is assigned this 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 pointers to the matching controls.

Note that most of the time the action properties will provide you with all of the information you need and will not have to interact with the COM controls at all. The exceptions to this rule are the few controls that contain special information that is not maintained by the action. Menu items with peControlType types defined as combos (xtpControlComboBox) and edits (xtpControlEdit) are examples of this. See cCJCommandBarComboBox and cCJCommandBarEdit for more about working with these types of items.

Return Value

Returns a COM pointer to the first COM control using this action