CustomTaskPane 接口

2011-08-12

代表 Microsoft Office 应用程序中的自定义任务窗格。

命名空间： Microsoft.Office.Tools
程序集： Microsoft.Office.Tools.Common（在 Microsoft.Office.Tools.Common.dll 中）

语法

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

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

CustomTaskPane 类型公开以下成员。

属性

	名称	说明
	Control	获取提供自定义任务窗格用户界面的 UserControl。
	DockPosition	获取或设置一个指定自定义任务窗格相对于应用程序窗口的位置的值。
	DockPositionRestrict	获取或设置一个禁止自定义任务窗格停靠在指定位置的值。
	Height	获取或设置自定义任务窗格的高度（以磅为单位）。
	Title	获取自定义任务窗格的标题。
	Visible	获取或设置一个指定自定义任务窗格是否可见的值。
	Width	获取或设置自定义任务窗格的宽度（以磅为单位）。
	Window	获取自定义任务窗格与之关联的文档窗口。

页首

方法

	名称	说明
	Dispose	执行与释放或重置非托管资源相关的应用程序定义的任务。（继承自 IDisposable。）

页首

事件

	名称	说明
	DockPositionChanged	当用户更改自定义任务窗格的停靠位置时，或者当代码更改 DockPosition 属性的值时发生。
	VisibleChanged	当用户显示或关闭自定义任务窗格时，或者当代码更改 Visible 属性的值时发生。

页首

备注

在应用程序级外接程序中使用 CustomTaskPane 对象可以修改自定义任务窗格，或者在自定义任务窗格的位置或可见性发生变化时做出响应。任务窗格是通常停靠在应用程序窗口一侧的用户界面面板。有关如何创建自定义任务窗格的信息，请参见自定义任务窗格概述。

若要控制自定义任务窗格的大小或位置，可以使用诸如 Height、Width 和 Visible 等属性。

若要在自定义任务窗格移动或可见性发生变化时做出响应，可以处理 DockPositionChanged 和 VisibleChanged 事件。

提示

此接口由 Visual Studio Tools for Office 运行时实现。不应在代码中实现此接口。有关更多信息，请参见 Visual Studio Tools for Office Runtime 概述。

用法

本文档介绍面向 .NET Framework 4 的 Office 项目中所用此类型的版本。在面向 .NET Framework 3.5 的项目中，此类型可能具有不同的成员，因此本文档为此类型提供的代码示例可能并不适用。有关在面向 .NET Framework 3.5 的项目中使用此类型的文档，请参见 Visual Studio 2008 文档中以下参考部分：https://go.microsoft.com/fwlink/?LinkId=160658。

示例

下面的代码示例演示如何使用 Add(UserControl, String) 方法创建自定义任务窗格。此示例使用 CustomTaskPane 对象的属性来设置自定义任务窗格的默认外观，并为 DockPositionChanged 事件定义事件处理程序。若要编译此示例，请将代码复制到支持自定义任务窗格的应用程序的外接程序项目中的 ThisAddIn 类。使用此示例中的 ThisAddIn_Startup 方法替换 ThisAddIn 类中的默认 ThisAddIn_Startup 方法。此示例还假定项目包含一个名为 MyUserControl 的 UserControl，且 UserControl 包含一个名为 FlowPanel 的 FlowLayoutPanel。

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;
        }
    }
}