Edit

Share via

Expose Lists of symbols provided by the library to the object manager

  • Article

The symbol-browsing tools, Class View, Object Browser, Call Browser and Find Symbol Results, pass requests for new data to the Visual Studio object manager. The object manager finds the appropriate libraries and requests new lists of symbols. The libraries respond by providing requested data to the Visual Studio object manager through the IVsSimpleObjectList2 interface. The Visual Studio object manager calls the methods in IVsSimpleObjectList2 interface to obtain the data and uses it to populate or update the views of the symbol-browsing tools.

A library may get requests for data when the tool is invoked, the node is expanded, or the view is refreshed. When a symbol-browsing tool is invoked for the first time, the object manager requests the library to provide the top-level list. When the user expands a list node, the library provides a list of children under that node. Every object manager inquiry contains an index of the item of interest. To display a new list, the object manager must determine how many items are in the list, the type of the items, their names, accessibility, and other properties.

Note

The following managed code examples demonstrate how to provide lists of symbols through implementing the IVsSimpleObjectList2 interface. The object manager calls the methods in this interface and uses the obtained data to populate or update the symbol-browsing tools.

For native code symbol provider implementation, use the IVsObjectList2 interface.

To provide lists of symbols to the object manager

  1. Get the number of items in the list of symbols by implementing the GetItemCount method. The following example demonstrates how the object manager obtains the information on the number of items in the list.

    protected System.Collections.Generic.SortedList<string, Method> m_Methods = new System.Collections.Generic.SortedList<string, Method>();

public int GetItemCount(out uint pCount)
{
    pCount = (uint)m_Methods.Count;
    return Microsoft.VisualStudio.VSConstants.S_OK;
}

  2. Get information about the categories and the attributes of a given list item by implementing the GetCategoryField2 method. The item categories are specified in the LIB_CATEGORY enumeration. The following example demonstrates how the object manager obtains attributes of items for a given category.

    public int GetCategoryField2(uint index, int Category, out uint pfCatField)
{
    pfCatField = 0;

    switch ((LIB_CATEGORY)Category)
    {
        case LIB_CATEGORY.LC_MEMBERTYPE:
            pfCatField = (uint)_LIBCAT_MEMBERTYPE.LCMT_METHOD;
            break;

        case LIB_CATEGORY.LC_MEMBERACCESS:
            {
                Method method = m_Methods.Values[(int)index];

                if (method.IsPublic)
                {
                    pfCatField = (uint)_LIBCAT_MEMBERACCESS.LCMA_PUBLIC;
                }
                else if (method.IsPrivate)
                {
                    pfCatField = (uint)_LIBCAT_MEMBERACCESS.LCMA_PRIVATE;
                }
                else if (method.IsFamily)
                {
                    pfCatField = (uint)_LIBCAT_MEMBERACCESS.LCMA_PROTECTED;
                }
                else if (method.IsFamilyOrAssembly)
                {
                    pfCatField = (uint)_LIBCAT_MEMBERACCESS.LCMA_PROTECTED |
                                 (uint)_LIBCAT_MEMBERACCESS.LCMA_PACKAGE;
                }
                else
                {
                    // Show everything else as internal.
                    pfCatField = (uint)_LIBCAT_MEMBERACCESS.LCMA_PACKAGE;
                }
            }
            break;

        case LIB_CATEGORY.LC_VISIBILITY:
            pfCatField = (uint)_LIBCAT_VISIBILITY.LCV_VISIBLE;
            break;

        case LIB_CATEGORY.LC_LISTTYPE:
            pfCatField = (uint)_LIB_LISTTYPE.LLT_MEMBERS;
            break;

        default:
            return Microsoft.VisualStudio.VSConstants.S_FALSE;
    }
    return Microsoft.VisualStudio.VSConstants.S_OK;
}

  3. Get the text representation of a given list item by implementing the GetTextWithOwnership method. The following example demonstrates how to obtain a full name of a given item.

    public int GetTextWithOwnership([System.Runtime.InteropServices.ComAliasNameAttribute("Microsoft.VisualStudio.OLE.Interop.ULONG")] uint index, [System.Runtime.InteropServices.ComAliasNameAttribute("Microsoft.VisualStudio.Shell.Interop.VSTREETEXTOPTIONS")] Microsoft.VisualStudio.Shell.Interop.VSTREETEXTOPTIONS tto, [System.Runtime.InteropServices.ComAliasNameAttribute("Microsoft.VisualStudio.OLE.Interop.WCHAR")] out string ppszText)
{
    ppszText = m_Methods.Values[(int)index].FullName;
    return Microsoft.VisualStudio.VSConstants.S_OK;
}

  4. Get the icon information for a given list item by implementing the GetDisplayData method. The icon represents the type (class, method, and so on), and accessibility (private, public, and so on) of a list item. The following example demonstrates how to obtain the icon information based on a given item attributes.

    public virtual int GetDisplayData(uint index, Microsoft.VisualStudio.Shell.Interop.VSTREEDISPLAYDATA[] pData)
{
    if (pData == null)
    {
        return Microsoft.VisualStudio.VSConstants.E_INVALIDARG;
    }

    Method method = m_Methods.Values[(int)index];

    int iImage = 12 * 6;    // See env\inc\OMGlyphs.h.

    const int OM_GLYPH_ACC_PUBLIC = 0;
    const int OM_GLYPH_ACC_INTERNAL = 1;
    const int OM_GLYPH_ACC_PROTECTED = 3;
    const int OM_GLYPH_ACC_PRIVATE = 4;

    if (method.IsPublic)
    {
        iImage += OM_GLYPH_ACC_PUBLIC;
    }
    else if (method.IsPrivate)
    {
        iImage += OM_GLYPH_ACC_PRIVATE;
    }
    else if (method.IsFamily)
    {
        iImage += OM_GLYPH_ACC_PROTECTED;
    }
    else if (method.IsFamilyOrAssembly)
    {
        iImage += OM_GLYPH_ACC_PROTECTED;
    }
    else
    {
        iImage += OM_GLYPH_ACC_INTERNAL;
    }

    pData[0].Image = (ushort)iImage;
    pData[0].SelectedImage = (ushort)iImage;

    return Microsoft.VisualStudio.VSConstants.S_OK;
}

  5. Get the information on whether a given list item is expandable by implementing the GetExpandable3 method. The following example demonstrates how to obtain the information on whether a given item can be expanded.

    public int GetExpandable(uint index, out int pfExpandable)
{
    pfExpandable = Microsoft.VisualStudio.VSIP.Samples.CallBrowser.Constants.TRUE;
    return Microsoft.VisualStudio.VSConstants.S_OK;
}

public int GetExpandable3(uint index, uint ListTypeExcluded, out int pfExpandable)
{
    return GetExpandable(index, out pfExpandable);
}

  6. Get a child list of symbols of a given list item by implementing the GetList2 method. The following example demonstrates how to obtain a child list of symbols of a given item for Call or Callers graphs.

    // Call graph list.
public class CallsList :
    ResultsList,
    Microsoft.VisualStudio.Shell.Interop.IVsSimpleObjectList2
{
    public CallsList(Library library) :
        base(library)
    {
    }

    public int GetList2(uint index, uint ListType, uint flags, Microsoft.VisualStudio.Shell.Interop.VSOBSEARCHCRITERIA2[] pobSrch, out Microsoft.VisualStudio.Shell.Interop.IVsSimpleObjectList2 ppList)
    {
        return base.GetCallsList(index, out ppList);
    }
}

// Callers graph list.
public class CallersList :
    ResultsList,
    Microsoft.VisualStudio.Shell.Interop.IVsSimpleObjectList2
{
    public CallersList(Library library) :
        base(library)
    {
    }

    public int GetList2(uint index, uint ListType, uint flags, Microsoft.VisualStudio.Shell.Interop.VSOBSEARCHCRITERIA2[] pobSrch, out Microsoft.VisualStudio.Shell.Interop.IVsSimpleObjectList2 ppList)
    {
        return base.GetCallersList(index, out ppList);
    }
}

// Call graph list.
public int GetCallsList(uint index, out Microsoft.VisualStudio.Shell.Interop.IVsSimpleObjectList2 ppList)
{
    ppList = null;
    ResultsList callsList = new CallsList(m_Library);

    Method method = m_Methods.Values[(int)index];
    string strMethod = method.m_strPrototype;

    System.Collections.Generic.List<CallInstance> Calls = m_Library.CallGraph.GetCallGraph(method);

    for (int i = 0; i < Calls.Count; i++)
    {
        Method caller = Calls[i].m_Target;
        callsList.AddMethod(caller);
    }

    ppList = (Microsoft.VisualStudio.Shell.Interop.IVsSimpleObjectList2)(callsList);
    return Microsoft.VisualStudio.VSConstants.S_OK;
}

// Callers graph list.
public int GetCallersList(uint index, out Microsoft.VisualStudio.Shell.Interop.IVsSimpleObjectList2 ppList)
{
    ppList = null;
    ResultsList callersList = new CallersList(m_Library);

    Method method = m_Methods.Values[(int)index];
    string strMethod = method.m_strPrototype;

    System.Collections.Generic.List<CallInstance> Callers = m_Library.CallGraph.GetCallersGraph(method);

    for (int i = 0; i < Callers.Count; i++)
    {
        Method caller = Callers[i].m_Source;
        callersList.AddMethod(caller);
    }

    ppList = (Microsoft.VisualStudio.Shell.Interop.IVsSimpleObjectList2)(callersList);
    return Microsoft.VisualStudio.VSConstants.S_OK;
}

// Get a child list of symbols for a given list item.
public int GetList2(uint index, uint ListType, uint flags, Microsoft.VisualStudio.Shell.Interop.VSOBSEARCHCRITERIA2[] pobSrch, out Microsoft.VisualStudio.Shell.Interop.IVsSimpleObjectList2 ppList)
{
    ppList = null;

    Method method = m_Methods.Values[(int)index];
    string strMethod = method.m_strPrototype;

    // Determine if the list belongs to Call or Callers graphs.
    if ((uint)(m_nFlags & (uint)Microsoft.VisualStudio.Shell.Interop._VSOBSEARCHOPTIONS2.VSOBSO_CALLSFROM) > 0)
    {
        // Build the list for the Call graph.
        return base.GetCallsList(index, out ppList);
    }
    else if ((uint)(m_nFlags & (uint)Microsoft.VisualStudio.Shell.Interop._VSOBSEARCHOPTIONS2.VSOBSO_CALLSTO) > 0)
    {
        // Build the list for the Callers graph.
        return base.GetCallersList(index, out ppList);
    }

    return Microsoft.VisualStudio.VSConstants.E_FAIL;
}

Related content