IVsUIHierarchy.QueryStatusCommand Method

Article
03/06/2013

Queries the object for the command status.

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

Syntax

'Declaration
Function QueryStatusCommand ( _
    itemid As UInteger, _
    ByRef pguidCmdGroup As Guid, _
    cCmds As UInteger, _
    <OutAttribute> prgCmds As OLECMD(), _
    <OutAttribute> pCmdText As IntPtr _
) As Integer

int QueryStatusCommand(
    uint itemid,
    ref Guid pguidCmdGroup,
    uint cCmds,
    OLECMD[] prgCmds,
    IntPtr pCmdText
)

int QueryStatusCommand(
    [InAttribute] unsigned int itemid, 
    [InAttribute] Guid% pguidCmdGroup, 
    [InAttribute] unsigned int cCmds, 
    [InAttribute] [OutAttribute] array<OLECMD>^ prgCmds, 
    [InAttribute] [OutAttribute] IntPtr pCmdText
)

abstract QueryStatusCommand : 
        itemid:uint32 * 
        pguidCmdGroup:Guid byref * 
        cCmds:uint32 * 
        prgCmds:OLECMD[] byref * 
        pCmdText:IntPtr byref -> int

function QueryStatusCommand(
    itemid : uint, 
    pguidCmdGroup : Guid, 
    cCmds : uint, 
    prgCmds : OLECMD[], 
    pCmdText : IntPtr
) : int

Parameters

itemid
Type: System.UInt32
[in] Identifier of the item affected by this command. For a list of itemid values, see VSITEMID. For single selection, this is the actual item ID. For multiple selections, set itemid equal to VSITEMID_SELECTION.

pguidCmdGroup
Type: System.Guid%
[in, unique] Pointer to a unique identifier of the command group. The pguidCmdGroup parameter can be nulla null reference (Nothing in Visual Basic) to specify the standard group.

cCmds
Type: System.UInt32
[in] The number of commands in the prgCmds array.

prgCmds
Type: array<Microsoft.VisualStudio.OLE.Interop.OLECMD[]
[in, out, size_is(cCmds)] A caller-allocated array of OLECMD structures that indicate the commands for which the caller requires status information. This method fills the cmdf member of each structure with values taken from the OLECMDF enumeration.

pCmdText
Type: System.IntPtr
[in, out, unique] Pointer to an OLECMDTEXT structure in which to return the name and/or status information of a single command. Can be nulla null reference (Nothing in Visual Basic) to indicate that the caller does not require this information.

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 IVsUIHierarchy::QueryStatusCommand(
   [in] VSITEMID itemid,
   [in, unique] const GUID * pguidCmdGroup,
   [in] ULONG cCmds,
   [in, out, size_is(cCmds)] OLECMD prgCmds[],
   [in, out, unique] OLECMDTEXT *pCmdText
);

This method is similar to the M:Microsoft.VisualStudio.OLE.Interop.IOleCommandTarget.Exec(System.Guid@,System.UInt32,System.UInt32,System.IntPtr,System.IntPtr) method, which does not support hierarchies. The ExecCommand method additionally includes the itemid parameter, which identifies the hierarchy item to which the command applies.

The environment executes this method when the UI hierarchy window has focus. The UI hierarchy window delegates all menu or toolbar commands to the UIHierarchy object that is the common parent for the selection. This provides the UIHierarchy object the option to handle commands that only apply when the UI hierarchy window has focus. Examples include the Delete and Remove commands.

Do not also handle these commands using the IOleCommandTarget interface on which QueryInterface can be run from the IVsHierarchy interface. The IOleCommandTarget of the active project is included in the usual command routing of the environment, even when another window (for example, a document window) has focus.

If the UI hierarchy window is not the active window, but it is still the active hierarchy, meaning that it is the last hierarchy to have been selected, then any commands that involve the active hierarchy are sent through the IOleCommandTarget interface instead of the IVsUIHierarchy interface. For example, if the selection is changed from the Solution Explorer to the task list, then the Solution Explorer is the active hierarchy, but the active window is the task list. In this case, any commands that are related to the active hierarchy, such as adding an item to the project, are sent through the IOleCommandTarget interface.

Commands like adding a project item should not be handled by the IVsUIHierarchy methods because they will not be available from outside of the hierarchy window. Only use IVsUIHierarchy to handle commands that require the UI Hierarchy window to have focus, or that act on a specific item within the hierarchy.

.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