CustomTaskPane Interface

Represents a custom task pane in a Microsoft Office application.

Namespace:  Microsoft.Office.Tools
Assemblies:   Microsoft.Office.Tools.Common.v4.0.Utilities (in Microsoft.Office.Tools.Common.v4.0.Utilities.dll)
  Microsoft.Office.Tools.Outlook.v4.0.Utilities (in Microsoft.Office.Tools.Outlook.v4.0.Utilities.dll)
  Microsoft.Office.Tools.Excel.v4.0.Utilities (in Microsoft.Office.Tools.Excel.v4.0.Utilities.dll)
  Microsoft.Office.Tools.Common (in Microsoft.Office.Tools.Common.dll)
  Microsoft.Office.Tools.Word.v4.0.Utilities (in Microsoft.Office.Tools.Word.v4.0.Utilities.dll)

Syntax

'Declaration
<GuidAttribute("881b42fd-484d-4494-8500-779de4e4aac1")> _
Public Interface CustomTaskPane _
    Inherits IDisposable

[GuidAttribute("881b42fd-484d-4494-8500-779de4e4aac1")]
public interface CustomTaskPane : IDisposable

The CustomTaskPane type exposes the following members.

Properties

	Name	Description
	Control	Gets the UserControl that provides the user interface of the custom task pane.
	DockPosition	Gets or sets a value that specifies where the custom task pane is located relative to the application window.
	DockPositionRestrict	Gets or sets a value that prevents the custom task pane from being docked in the specified position.
	Height	Gets or sets the height of the custom task pane, in points.
	Title	Gets the title of the custom task pane.
	Visible	Gets or sets a value that specifies whether the custom task pane is visible.
	Width	Gets or sets the width of the custom task pane, in points.
	Window	Gets the document window that the custom task pane is associated with.

Top

Methods

	Name	Description
	Dispose	Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources. (Inherited from IDisposable.)

Top

Events

	Name	Description
	DockPositionChanged	Occurs when the user changes the dock position of the custom task pane, or when code changes the value of the DockPosition property.
	VisibleChanged	Occurs when the user displays or closes the custom task pane, or when code changes the value of the Visible property.

Top

Remarks

Use a CustomTaskPane object in an application-level add-in to modify a custom task pane, or to respond when the location or visibility of the custom task pane changes. Task panes are user interface panels that are typically docked to one side of an application window. For information about how to create custom task panes, see Custom Task Panes.

To control the size or location of the custom task pane, you can use properties such as Height, Width, and Visible.

To respond when the custom task pane moves or changes visibility, you can handle the DockPositionChanged and VisibleChanged events.

Note

This interface is implemented by the Visual Studio Tools for Office runtime. It is not intended to be implemented in your code. For more information, see Visual Studio Tools for Office Runtime Overview.

Usage

This documentation describes the version of this type that is used in Office projects that target the .NET Framework 4 and the .NET Framework 4.5. In projects that target the .NET Framework 3.5, this type might have different members and the code examples provided for this type might not work. For documentation about this type in projects that target the .NET Framework 3.5, see the following reference section in the Visual Studio 2008 documentation: https://go.microsoft.com/fwlink/?LinkId=160658.

Examples

The following code example demonstrates how to create a custom task pane by using the Add(UserControl, String) method. The example uses properties of the CustomTaskPane object to set the default appearance of the custom task pane, and it defines an event handler for the DockPositionChanged event. To compile this example, copy the code into the ThisAddIn class in an add-in project for an application that supports custom task panes. Replace the default ThisAddIn_Startup method in the ThisAddIn class with the ThisAddIn_Startup method in this example. This example also assumes that the project contains a UserControl named MyUserControl, and the UserControl contains a FlowLayoutPanel named FlowPanel.

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 

Private Sub myCustomTaskPane_DockPositionChanged(ByVal sender As Object, _
    ByVal e As EventArgs) Handles myCustomTaskPane.DockPositionChanged

    Dim taskPane As Microsoft.Office.Tools.CustomTaskPane = _
        TryCast(sender, Microsoft.Office.Tools.CustomTaskPane)

    If taskPane IsNot Nothing Then 

        ' Adjust sizes of user control and flow panel to fit current task pane size. 
        Dim userControl As MyUserControl = TryCast(taskPane.Control, MyUserControl)
        Dim paneSize As System.Drawing.Size = _
            New System.Drawing.Size(taskPane.Width, taskPane.Height)
        userControl.Size = paneSize
        userControl.FlowPanel.Size = paneSize

        ' Adjust flow direction of controls on the task pane. 
        If taskPane.DockPosition = _
            Office.MsoCTPDockPosition.msoCTPDockPositionTop Or _
            taskPane.DockPosition = _
            Office.MsoCTPDockPosition.msoCTPDockPositionBottom Then

            userControl.FlowPanel.FlowDirection = _
                System.Windows.Forms.FlowDirection.LeftToRight
        Else
            userControl.FlowPanel.FlowDirection = _
                System.Windows.Forms.FlowDirection.TopDown
        End If 
    End If 
End Sub

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 void myCustomTaskPane_DockPositionChanged(object sender, EventArgs e)
{
    Microsoft.Office.Tools.CustomTaskPane taskPane =
        sender as Microsoft.Office.Tools.CustomTaskPane;

    if (taskPane != null)
    {
        // Adjust sizes of user control and flow panel to fit current task pane size.
        MyUserControl userControl = taskPane.Control as MyUserControl;
        System.Drawing.Size paneSize = new System.Drawing.Size(taskPane.Width, taskPane.Height);
        userControl.Size = paneSize;
        userControl.FlowPanel.Size = paneSize;

        // Adjust flow direction of controls on the task pane. 
        if (taskPane.DockPosition == 
            Office.MsoCTPDockPosition.msoCTPDockPositionTop ||
            taskPane.DockPosition ==
            Office.MsoCTPDockPosition.msoCTPDockPositionBottom)
        {
            userControl.FlowPanel.FlowDirection =
                System.Windows.Forms.FlowDirection.LeftToRight;
        }
        else
        {
            userControl.FlowPanel.FlowDirection =
                System.Windows.Forms.FlowDirection.TopDown;
        }
    }
}

See Also

Reference

Microsoft.Office.Tools Namespace

Other Resources

Getting Started Programming Application-Level Add-Ins

Custom Task Panes

How to: Add a Custom Task Pane to an Application

Walkthrough: Automating an Application from a Custom Task Pane