Control.Invoke Method

Definition

Executes a delegate on the thread that owns the control's underlying window handle.

Overloads

Invoke(Action)

Executes the specified delegate on the thread that owns the control's underlying window handle.

Invoke(Delegate)

Executes the specified delegate on the thread that owns the control's underlying window handle.

Invoke(Delegate, Object[])

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

Invoke<T>(Func<T>)

Executes the specified delegate on the thread that owns the control's underlying window handle.

Invoke(Action)

Source:
Control.cs
Source:
Control.cs
Source:
Control.cs

Executes the specified delegate on the thread that owns the control's underlying window handle.

public void Invoke (Action method);

Parameters

method
Action

A delegate that contains a method to be called in the control's thread context.

Applies to

Windows Desktop 9 and other versions
Product Versions
Windows Desktop 6, 7, 8, 9

Invoke(Delegate)

Source:
Control.cs
Source:
Control.cs
Source:
Control.cs

Executes the specified delegate on the thread that owns the control's underlying window handle.

public object Invoke (Delegate method);

Parameters

method
Delegate

A delegate that contains a method to be called in the control's thread context.

Returns

The return value from the delegate being invoked, or null if the delegate has no return value.

Examples

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. When the user clicks on the button, Invoke runs the delegate.

/*
The following example demonstrates the 'Invoke(Delegate)' method of 'Control class.
A 'ListBox' and a 'Button' control are added to a form, containing a delegate
which encapsulates a method that adds items to the listbox. This function is executed
on the thread that owns the underlying handle of the form. When user clicks on button
the above delegate is executed using 'Invoke' method.


*/

using System;
using System.Drawing;
using System.Windows.Forms;
using System.Threading;

   public class MyFormControl : Form
   {
      public delegate void AddListItem();
      public AddListItem myDelegate;
      private Button myButton;
      private Thread myThread;
      private ListBox myListBox;
      public MyFormControl()
      {
         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";
         myButton.Click += new EventHandler(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(AddListItemMethod);
      }
      static void Main()
      {
         MyFormControl myForm = new MyFormControl();
         myForm.ShowDialog();
      }
      public void AddListItemMethod()
      {
         String myItem;
         for(int i=1;i<6;i++)
         {
            myItem = "MyListItem" + i.ToString();
            myListBox.Items.Add(myItem);
            myListBox.Update();
            Thread.Sleep(300);
         }
      }
      private void Button_Click(object sender, EventArgs e)
      {
         myThread = new Thread(new ThreadStart(ThreadFunction));
         myThread.Start();
      }
      private void ThreadFunction()
      {
         MyThreadClass myThreadClassObject  = new MyThreadClass(this);
         myThreadClassObject.Run();
      }
   }

// The following code assumes a 'ListBox' and a 'Button' control are added to a form, 
// containing a delegate which encapsulates a method that adds items to the listbox.

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

      public void Run()
      {
         // Execute the specified delegate on the thread that owns
         // 'myFormControl1' control's underlying window handle.
         myFormControl1.Invoke(myFormControl1.myDelegate);
      }
   }

Remarks

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.

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

Note

In addition to the InvokeRequired property, there are four methods on a control that are thread safe: Invoke, BeginInvoke, EndInvoke, and CreateGraphics if the handle for the control has already been created. Calling CreateGraphics before the control's handle has been created on a background thread can cause illegal cross thread calls. 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.

Note

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

See also

Applies to

.NET Framework 4.8.1 and other versions
Product Versions
.NET Framework 1.1, 2.0, 3.0, 3.5, 4.0, 4.5, 4.5.1, 4.5.2, 4.6, 4.6.1, 4.6.2, 4.7, 4.7.1, 4.7.2, 4.8, 4.8.1
Windows Desktop 3.0, 3.1, 5, 6, 7, 8, 9

Invoke(Delegate, Object[])

Source:
Control.cs
Source:
Control.cs
Source:
Control.cs

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

public object Invoke (Delegate method, object[] args);
public object Invoke (Delegate method, params object[] args);
public object Invoke (Delegate method, params object?[]? args);

Parameters

method
Delegate

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

args
Object[]

An array of objects to pass as arguments to the specified method. This parameter can be null if the method takes no arguments.

Returns

An Object that contains the return value from the delegate being invoked, or null if the delegate has no return value.

Implements

Examples

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.

using System;
using System.Drawing;
using System.Windows.Forms;
using System.Threading;

   public class MyFormControl : Form
   {
      public delegate void AddListItem(String myString);
      public AddListItem myDelegate;
      private Button myButton;
      private Thread myThread;
      private ListBox myListBox;
      public MyFormControl()
      {
         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";
         myButton.Click += new EventHandler(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(AddListItemMethod);
      }
      static void Main()
      {
         MyFormControl myForm = new MyFormControl();
         myForm.ShowDialog();
      }
      public void AddListItemMethod(String myString)
      {
            myListBox.Items.Add(myString);
      }
      private void Button_Click(object sender, EventArgs e)
      {
         myThread = new Thread(new ThreadStart(ThreadFunction));
         myThread.Start();
      }
      private void ThreadFunction()
      {
         MyThreadClass myThreadClassObject  = new MyThreadClass(this);
         myThreadClassObject.Run();
      }
   }
   public class MyThreadClass
   {
      MyFormControl myFormControl1;
      public MyThreadClass(MyFormControl myForm)
      {
         myFormControl1 = myForm;
      }
      String myString;

      public void Run()
      {

         for (int i = 1; i <= 5; i++)
         {
            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});
         }
      }
   }

Remarks

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.

Note

In addition to the InvokeRequired property, there are four methods on a control that are thread safe: Invoke, BeginInvoke, EndInvoke, and CreateGraphics if the handle for the control has already been created. Calling CreateGraphics before the control's handle has been created on a background thread can cause illegal cross thread calls. 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 parameters will depend on the args value:

  • If no parameters are passed, the sender parameter will contain this control and the event parameter will contain EventArgs.Empty.
  • When a single parameter is passed, the sender parameter will contain the first args element and the event parameter will contain EventArgs.Empty.
  • If more than one parameter is passed, the sender parameter will contain the first element from args, and the EventArgs parameter will contain the second element.

A call to an EventHandler or MethodInvoker delegate will be faster than a call to another type of delegate.

Note

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

See also

Applies to

.NET Framework 4.8.1 and other versions
Product Versions
.NET Framework 1.1, 2.0, 3.0, 3.5, 4.0, 4.5, 4.5.1, 4.5.2, 4.6, 4.6.1, 4.6.2, 4.7, 4.7.1, 4.7.2, 4.8, 4.8.1
Windows Desktop 3.0, 3.1, 5, 6, 7, 8, 9

Invoke<T>(Func<T>)

Source:
Control.cs
Source:
Control.cs
Source:
Control.cs

Executes the specified delegate on the thread that owns the control's underlying window handle.

public T Invoke<T> (Func<T> method);

Type Parameters

T

The return type of the method.

Parameters

method
Func<T>

A function to be called in the control's thread context.

Returns

T

The return value from the function being invoked.

Applies to

Windows Desktop 9 and other versions
Product Versions
Windows Desktop 6, 7, 8, 9