IVsTaskList.RegisterCustomCategory Method

Article
10/26/2012

Registers a custom category with the task list.

Namespace: Microsoft.VisualStudio.Shell.Interop
Assembly: Microsoft.VisualStudio.Shell.Interop (in Microsoft.VisualStudio.Shell.Interop.dll)

Syntax

'Declaration
Function RegisterCustomCategory ( _
    ByRef guidCat As Guid, _
    dwSortOrder As UInteger, _
    <OutAttribute> pCat As VSTASKCATEGORY() _
) As Integer

'Usage
Dim instance As IVsTaskList 
Dim guidCat As Guid 
Dim dwSortOrder As UInteger 
Dim pCat As VSTASKCATEGORY()
Dim returnValue As Integer 

returnValue = instance.RegisterCustomCategory(guidCat, _
    dwSortOrder, pCat)

int RegisterCustomCategory(
    ref Guid guidCat,
    uint dwSortOrder,
    VSTASKCATEGORY[] pCat
)

int RegisterCustomCategory(
    Guid% guidCat, 
    [InAttribute] unsigned int dwSortOrder, 
    [OutAttribute] array<VSTASKCATEGORY>^ pCat
)

function RegisterCustomCategory(
    guidCat : Guid, 
    dwSortOrder : uint, 
    pCat : VSTASKCATEGORY[]
) : int

Parameters

guidCat
Type: System.Guid%

[in] GUID of the custom category you wish to register.

dwSortOrder
Type: System.UInt32

[in] The requested sort placement within VSTASKCATEGORY for the custom category.

pCat
Type: array<Microsoft.VisualStudio.Shell.Interop.VSTASKCATEGORY[]

[out] Pointer to the actual sort placement of the custom category within VSTASKCATEGORY.

Return Value

Type: System.Int32
If the method succeeds, it returns S_OK. If it fails, it returns an error code.

Remarks

COM Signature

From vsshell.idl:

HRESULT IVsTaskList::RegisterCustomCategory(
   REFGUID guidCat,
   [in] DWORD dwSortOrder,
   [out] VSTASKCATEGORY *pCat
);

Each custom category must have its own GUID. The dwSortOrder parameter is the place in the VSTASKCATEGORY enumeration where the custom category should sort. For example, if you want your custom category to be placed after Code Sense errors (CAT_CODESENSE = 30) but before shortcuts (CAT_SHORTCUTS = 40) during a sort, you can pass in a value of 31 for dwSortOrder. If 31 is already being used by another custom category, the task list scans up until it finds a sort position not being used. The actual position within VSTASKCATEGORY that the task list assigns to your custom category is what is passed back as the *pCat parameter.

Much of the effect of a custom category can be achieved without actually implementing a custom category. Each task item can be given its own bitmap image and tasks can be sorted together by giving them the same subcategory. A few reasons why you would want to implement custom categories include:

It is important that your category be sorted in a particular place in the task list.
You don't want to use the CAT_MISC enumeration in VSTASKCATEGORY because other tasks might also be using it. In this case, all of the CAT_MISC tasks would be sorted together, making it impossible to assure that your tasks will be placed together during a sort.
You want a custom view where only your tasks are shown in the task list.

Note

Creating a custom category does not automatically create a custom view associated with it. Custom views are registry based, and are described in the AutoFilter2.

.NET Framework Security

Full trust for the immediate caller. This member cannot be used by partially trusted code. For more information, see Using Libraries from Partially Trusted Code.

Share via