CustomTaskPaneCollection.Add Method

Definition

Namespace:

Microsoft.Office.Tools

Assembly:

Microsoft.Office.Tools.Common.dll

Overloads

Add(UserControl, String)	Creates a new CustomTaskPane and adds it to the current CustomTaskPaneCollection. The custom task pane is based on the specified UserControl and has the specified title.
Add(UserControl, String, Object)	Creates a new CustomTaskPane and adds it to the current CustomTaskPaneCollection. The custom task pane is based on the specified UserControl, has the specified title, and is associated with the specified application window.

Add(UserControl, String)

Creates a new CustomTaskPane and adds it to the current CustomTaskPaneCollection. The custom task pane is based on the specified UserControl and has the specified title.

public:
 Microsoft::Office::Tools::CustomTaskPane ^ Add(System::Windows::Forms::UserControl ^ control, System::String ^ title);

public Microsoft.Office.Tools.CustomTaskPane Add (System.Windows.Forms.UserControl control, string title);

abstract member Add : System.Windows.Forms.UserControl * string -> Microsoft.Office.Tools.CustomTaskPane

Public Function Add (control As UserControl, title As String) As CustomTaskPane

Parameters

control

UserControl

A UserControl that provides the user interface for the new custom task pane.

title

String

The text that appears in the title bar of the new custom task pane.

Returns

CustomTaskPane

A CustomTaskPane that represents the new custom task pane.

Exceptions

ArgumentNullException

control or title is null.

ObjectDisposedException

The Microsoft.Office.Tools.CustomTaskPaneCollection.Dispose method has already been called on the CustomTaskPaneCollection.

Examples

The following code example demonstrates how to create a custom task pane by using the Add(UserControl, String) method. The example also uses properties of the CustomTaskPane object to modify the default appearance of the custom task pane. This code example is part of a larger example provided for CustomTaskPane.

private MyUserControl myUserControl1;
private Microsoft.Office.Tools.CustomTaskPane myCustomTaskPane;

private void ThisAddIn_Startup(object sender, System.EventArgs e)
{
    myUserControl1 = new MyUserControl();
    myCustomTaskPane = this.CustomTaskPanes.Add(myUserControl1,
        "New Task Pane");

    myCustomTaskPane.DockPosition =
        Office.MsoCTPDockPosition.msoCTPDockPositionFloating;
    myCustomTaskPane.Height = 500;
    myCustomTaskPane.Width = 500;

    myCustomTaskPane.DockPosition =
        Office.MsoCTPDockPosition.msoCTPDockPositionRight;
    myCustomTaskPane.Width = 300;

    myCustomTaskPane.Visible = true;
    myCustomTaskPane.DockPositionChanged +=
        new EventHandler(myCustomTaskPane_DockPositionChanged);
}

Private myUserControl1 As MyUserControl
Private WithEvents myCustomTaskPane As Microsoft.Office.Tools.CustomTaskPane

Private Sub ThisAddIn_Startup(ByVal sender As Object, ByVal e As System.EventArgs) _
    Handles Me.Startup

    myUserControl1 = New MyUserControl()
    myCustomTaskPane = Me.CustomTaskPanes.Add(myUserControl1, "New Task Pane")

    With myCustomTaskPane
        .DockPosition = Office.MsoCTPDockPosition.msoCTPDockPositionFloating
        .Height = 500
        .Width = 500
        .DockPosition = Office.MsoCTPDockPosition.msoCTPDockPositionRight
        .Width = 300
        .Visible = True
    End With
End Sub

Remarks

Use this method to create a new CustomTaskPane that is associated with the active window of the Microsoft Office application.

Although a CustomTaskPaneCollection object is a collection of CustomTaskPane objects, the Add method accepts UserControl objects instead of CustomTaskPane objects. For more information, see Custom Task Panes.

If you want to specify a particular window and associate the custom task pane with it, use the Add(UserControl, String, Object) method.

Add(UserControl, String, Object)

Creates a new CustomTaskPane and adds it to the current CustomTaskPaneCollection. The custom task pane is based on the specified UserControl, has the specified title, and is associated with the specified application window.

public:
 Microsoft::Office::Tools::CustomTaskPane ^ Add(System::Windows::Forms::UserControl ^ control, System::String ^ title, System::Object ^ window);

public Microsoft.Office.Tools.CustomTaskPane Add (System.Windows.Forms.UserControl control, string title, object window);

abstract member Add : System.Windows.Forms.UserControl * string * obj -> Microsoft.Office.Tools.CustomTaskPane

Public Function Add (control As UserControl, title As String, window As Object) As CustomTaskPane

Parameters

control

UserControl

A UserControl that provides the user interface for the new custom task pane.

title

String

The text that appears in the title bar of the new custom task pane.

window

Object

An object that represents the application window to associate the new custom task pane with.

Returns

CustomTaskPane

A CustomTaskPane that represents the new custom task pane.

Exceptions

ArgumentNullException

control or title is null.

ObjectDisposedException

The Microsoft.Office.Tools.CustomTaskPaneCollection.Dispose method has already been called on the CustomTaskPaneCollection.

Remarks

Use this method to create a new CustomTaskPane that is associated with a specific application window. This method is useful if you want to create custom task panes that are visible with multiple Inspectors or Explorers in Outlook, or with multiple documents in Word or InfoPath.

The type of the window parameter depends on the application. The following table lists the valid types of the window parameter.

Application	Parameter type
Word	Microsoft.Office.Interop.Word.Window
Excel	Microsoft.Office.Interop.Excel.Window
PowerPoint	Microsoft.Office.Interop.PowerPoint.DocumentWindow
InfoPath	Microsoft.Office.Interop.InfoPath.WindowObject
Outlook	Microsoft.Office.Interop.Outlook.Explorer -or- Microsoft.Office.Interop.Outlook.Inspector

Although a CustomTaskPaneCollection is a collection of CustomTaskPane objects, the Add method accepts UserControl objects instead of CustomTaskPane objects. For more information, see Custom Task Panes.