Export (0) Print
Expand All

Control.Invoke Method (Delegate, Object[])

Executes the specified delegate, on the thread that owns the control's underlying window handle, with the specified list of arguments.

Namespace: System.Windows.Forms
Assembly: System.Windows.Forms (in system.windows.forms.dll)

'Declaration
Public Function Invoke ( _
	method As Delegate, _
	ParamArray args As Object() _
) As Object
'Usage
Dim instance As Control
Dim method As Delegate
Dim args As Object()
Dim returnValue As Object

returnValue = instance.Invoke(method, args)
public final Object Invoke (
	Delegate method, 
	Object[] args
)
public final function Invoke (
	method : Delegate, 
	... args : Object[]
) : Object

Parameters

method

A delegate to a method that takes parameters of the same number and type that are contained in the args parameter.

args

An array of objects to pass as arguments to the specified method. This parameter can be a null reference (Nothing in Visual Basic) if the method takes no arguments.

Return Value

An Object that contains the return value from the delegate being invoked, or a null reference (Nothing in Visual Basic) if the delegate has no return value.

Delegates are similar to function pointers in C or C++ languages. Delegates encapsulate a reference to a method inside a delegate object. The delegate object can then be passed to code that calls the referenced method, and the method to be invoked can be unknown at compile time. Unlike function pointers in C or C++, delegates are object-oriented, type-safe, and more secure.

If the control's handle does not exist yet, this method searches up the control's parent chain until it finds a control or form that does have a window handle. If no appropriate handle can be found, this method throws an exception. Exceptions that are raised during the call will be propagated back to the caller.

NoteNote

In addition to the InvokeRequired property, there are four methods on a control that are thread safe: Invoke, BeginInvoke, EndInvoke, and CreateGraphics. For all other method calls, you should use one of the invoke methods to marshal the call to the control's thread.

The delegate can be an instance of EventHandler, in which case the sender parameter will contain this control, and the event parameter will contain EventArgs.Empty. The delegate can also be an instance of MethodInvoker, or any other delegate that takes a void parameter list. A call to an EventHandler or MethodInvoker delegate will be faster than a call to another type of delegate.

NoteNote

An exception might be thrown if the thread that should process the message is no longer active.

Windows Mobile for Pocket PC, Windows Mobile for Smartphone, Windows CE Platform Note: In .NET Compact Framework applications, the delegate must be an instance of EventHandler. For an example, see Delegates Sample.

The following code example shows controls that contain a delegate. The delegate encapsulates a method that adds items to the list box, and this method is executed on the thread that owns the underlying handle of the form, using the specified arguments. When the user clicks on the button, Invoke runs the delegate.

Imports System
Imports System.Drawing
Imports System.Windows.Forms
Imports System.Threading

Public Class MyFormControl
   Inherits Form

   Delegate Sub AddListItem(myString As String)
   Public myDelegate As AddListItem
   Private myButton As Button
   Private myThread As Thread
   Private myListBox As ListBox

   Public Sub New()
      myButton = New Button()
      myListBox = New ListBox()
      myButton.Location = New Point(72, 160)
      myButton.Size = New Size(152, 32)
      myButton.TabIndex = 1
      myButton.Text = "Add items in list box"
      AddHandler myButton.Click, AddressOf Button_Click
      myListBox.Location = New Point(48, 32)
      myListBox.Name = "myListBox"
      myListBox.Size = New Size(200, 95)
      myListBox.TabIndex = 2
      ClientSize = New Size(292, 273)
      Controls.AddRange(New Control() {myListBox, myButton})
      Text = " 'Control_Invoke' example "
      myDelegate = New AddListItem(AddressOf AddListItemMethod)
   End Sub 'New

   Shared Sub Main()
      Dim myForm As New MyFormControl()
      myForm.ShowDialog()
   End Sub 'Main

   Public Sub AddListItemMethod(myString As String)
      myListBox.Items.Add(myString)
   End Sub 'AddListItemMethod

   Private Sub Button_Click(sender As Object, e As EventArgs)
      myThread = New Thread(New ThreadStart(AddressOf ThreadFunction))
      myThread.Start()
   End Sub 'Button_Click

   Private Sub ThreadFunction()
      Dim myThreadClassObject As New MyThreadClass(Me)
      myThreadClassObject.Run()
   End Sub 'ThreadFunction
End Class 'MyFormControl

Public Class MyThreadClass
   Private myFormControl1 As MyFormControl

   Public Sub New(myForm As MyFormControl)
      myFormControl1 = myForm
   End Sub 'New
   Private myString As String

   Public Sub Run()

      Dim i As Integer
      For i = 1 To 5
         myString = "Step number " + i.ToString() + " executed"
         Thread.Sleep(400)
         ' Execute the specified delegate on the thread that owns
         ' 'myFormControl1' control's underlying window handle with
         ' the specified list of arguments.
         myFormControl1.Invoke(myFormControl1.myDelegate, New Object() {myString})
      Next i

   End Sub 'Run
End Class 'MyThreadClass

import System.*;
import System.Drawing.*;
import System.Windows.Forms.*;
import System.Threading.*;

public class MyFormControl extends Form
{
    /** @delegate 
     */
    public delegate void AddListItem(String myString);
    public AddListItem myDelegate;
    private Button myButton;
    private System.Threading.Thread myThread;
    private ListBox myListBox;

    public MyFormControl()
    {
        myButton = new Button();
        myListBox = new ListBox();
        myButton.set_Location(new Point(72, 160));
        myButton.set_Size(new Size(152, 32));
        myButton.set_TabIndex(1);
        myButton.set_Text("Add items in list box");
        myButton.add_Click(new EventHandler(Button_Click));
        myListBox.set_Location(new Point(48, 32));
        myListBox.set_Name("myListBox");
        myListBox.set_Size(new Size(200, 95));
        myListBox.set_TabIndex(2);
        set_ClientSize(new Size(292, 273));
        get_Controls().AddRange(new Control[] { myListBox, myButton });
        set_Text(" 'Control_Invoke' example ");
        myDelegate = new AddListItem(AddListItemMethod);
    } //MyFormControl

    public static void main(String[] args)
    {
        MyFormControl myForm = new MyFormControl();
        myForm.ShowDialog();
    } //main

    public void AddListItemMethod(String myString)
    {
        myListBox.get_Items().Add(myString);
    } //AddListItemMethod

    private void Button_Click(Object sender, EventArgs e)
    {
        myThread = new System.Threading.Thread(new ThreadStart(ThreadFunction));
        myThread.Start();
    } //Button_Click

    private void ThreadFunction() throws InterruptedException
    {
        MyThreadClass myThreadClassObject = new MyThreadClass(this);
        myThreadClassObject.Run();
    } //ThreadFunction
} //MyFormControl

public class MyThreadClass
{
    private MyFormControl myFormControl1;

    public MyThreadClass(MyFormControl myForm)
    {
        myFormControl1 = myForm;
    } //MyThreadClass

    private String myString;

    public void Run() throws InterruptedException
    {
        for (int i = 1; i <= 5; i++) {
            myString = "Step number " + System.Convert.ToString(i) 
                + " executed";
            Thread.sleep(400);

            // Execute the specified delegate on the thread that owns
            // 'myFormControl1' control's underlying window handle with
            // the specified list of arguments.
            myFormControl1.Invoke(myFormControl1.myDelegate, 
                new Object[] { myString });
        }
    } //Run
} //MyThreadClass

Windows 98, Windows 2000 SP4, Windows CE, Windows Millennium Edition, Windows Mobile for Pocket PC, Windows Mobile for Smartphone, Windows Server 2003, Windows XP Media Center Edition, Windows XP Professional x64 Edition, Windows XP SP2, Windows XP Starter Edition

The .NET Framework does not support all versions of every platform. For a list of the supported versions, see System Requirements.

.NET Framework

Supported in: 2.0, 1.1, 1.0

.NET Compact Framework

Supported in: 2.0

Community Additions

ADD
Show:
© 2014 Microsoft