Including a DTS Custom Task User Interface
To provide a user interface for setting properties, a custom task must implement the CustomTaskUI interface. This user interface, sometimes called a property page, is displayed:
- In Data Transformation Services (DTS) Designer when the DTS package is being implemented.
- In a DTS application when the object hierarchy is being created.
A user interface that is active when the custom task is executing is not controlled through the CustomTaskUI interface.
If a custom task does not implement CustomTaskUI, DTS Designer displays a default property grid in place of the custom task user interface.
For more information about building a custom task with a user interface, see DTS Example: Including a User Interface in Visual Basic and DTS Example: Including a User Interface in Visual C++.
CustomTaskUI Interface
In DTS Designer, a custom task calls the methods of CustomTaskUI to perform functions related to the display of user interface elements. When a custom task is part of a DTS application, the application calls the CustomTaskUI methods to perform these functions.
In Microsoft® Visual Basic®, this user interface is defined by the CustomTaskUI object from the Microsoft DTSPackage Object Library. In Microsoft Visual C++® it is defined by IDTSCustomTaskUI in the include file dtspkg.h.
The DTS CustomTaskUI interface includes the following elements.
| Element | Description |
|---|---|
| Initialize method | Called before other CustomTaskUI methods to allow the custom task to perform initializations. |
| New method | Called when a custom task is created. |
| Edit method | Called when the user interface is to be displayed for an existing custom task. |
| Delete method | Called when a custom task is to be removed from its package. |
| Help method | Called when Help for the custom task is to be displayed. |
| GetUIInfo method | Called when the parent application is to display a ToolTip, to determine if the custom task is to generate the ToolTip window. |
| CreateCustomToolTip method | Creates a custom ToolTip window and draws the ToolTip, when custom ToolTips are supported. |
As required by COM, all elements must be present, but they can be placeholders.
Caution It is strongly recommended that you check the parameters of all CustomTaskUI methods for validity before you use them. The caller may be a DTS application and you may not know how extensively the application has been tested.
Initialize Method
DTS Designer calls Initialize before New, Edit, Delete and Help. It is recommended that DTS applications follow this sequence so that the task can be used both within and outside of DTS Designer. The custom task can perform any initialization. The parameter, a reference to the Task object, can be saved for use by the subsequent method (for example, to access custom task properties).
New Method
DTS Designer calls New when the custom task icon is dragged to the design sheet. It is recommended that DTS applications call New after the custom task has been created with the New method of the Tasks collection.
Typically, the custom task displays a property page with default values. The parameter is the window handle of the DTS design sheet or of a window in the parent application.
If you do not implement CustomTaskUI, you see a default property grid in DTS Designer. If you implement CustomTaskUI but provide a placeholder for New, no user interface is displayed.
Edit Method
DTS Designer calls Edit when you right-click the custom task icon and click Properties. It is recommended that if DTS applications call Edit, they do so after the custom task has been created and values for custom task properties have been set.
Typically, the custom task displays a property page with current values. The parameter is the window handle of the DTS design sheet or of a window in the parent application.
If you do not implement CustomTaskUI, you see a default property grid. If you implement CustomTaskUI but provide a placeholder for Edit, no user interface is displayed.
Delete Method
DTS Designer calls Delete when you delete the custom task icon from the design sheet. The custom task can perform any cleanup. The parameter is the window handle of the DTS design sheet or of a window in the parent application.
Help Method
DTS Designer calls Help when you right-click the custom task icon and click Help.
Typically, the custom task displays a help topic (for example, by calling winhlp32.exe with a help file specification and topic ID). The parameter is the window handle of the DTS design sheet or of a window in the parent application.
If you do not implement CustomTaskUI, you see a generic help topic for custom tasks. If you implement CustomTaskUI but provide a placeholder for Help, no topic is displayed.
GetUIInfo Method
GetUIInfo is not implemented in DTS Designer. A DTS application can use this method to query the custom task for its tooltip text and description (for example, if the application used the custom task icon in its user interface). GetUIInfo also returns a value indicating whether the custom task generates a custom tooltip. GetUIInfo has the following parameters.
| Parameter | Description |
|---|---|
| pbstrToolTip | Returns the tooltip text. |
| pbstrDescription | Returns the tooltip description. |
| plVersion | Returns the custom task version number. |
| pFlags | Returns a value from DTSCustomTaskUIFlags that indicates whether the task generates a custom tooltip. |
CreateCustomToolTip Method
CreateCustomToolTip is not implemented in DTS Designer. A DTS application can call this method so that the custom task generates its custom tooltip after the GetUIInfo method has indicated the task can do so. CreateCustomToolTip has the following parameters.
| Parameter | Description |
|---|---|
| hwndParent | The handle of the window in the parent application where the TooltTip is to be drawn. |
| x, y | The co-ordinates where the ToolTip window is to be drawn. |
| plTipWindow | The parameter through which the ToolTip window handle is returned. |
The parent application is responsible for releasing the resources associated with the tooltip window.