Share via


IVsUIHierarchy.ExecCommand Method

Executes a command on a specific item within a UI hierarchy window, or on the hierarchy itself.

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

Syntax

'Declaration
Function ExecCommand ( _
    itemid As UInteger, _
    ByRef pguidCmdGroup As Guid, _
    nCmdID As UInteger, _
    nCmdexecopt As UInteger, _
    pvaIn As IntPtr, _
    pvaOut As IntPtr _
) As Integer
'Usage
Dim instance As IVsUIHierarchy 
Dim itemid As UInteger 
Dim pguidCmdGroup As Guid 
Dim nCmdID As UInteger 
Dim nCmdexecopt As UInteger 
Dim pvaIn As IntPtr 
Dim pvaOut As IntPtr 
Dim returnValue As Integer 

returnValue = instance.ExecCommand(itemid, _
    pguidCmdGroup, nCmdID, nCmdexecopt, _
    pvaIn, pvaOut)
int ExecCommand(
    uint itemid,
    ref Guid pguidCmdGroup,
    uint nCmdID,
    uint nCmdexecopt,
    IntPtr pvaIn,
    IntPtr pvaOut
)
int ExecCommand(
    [InAttribute] unsigned int itemid, 
    [InAttribute] Guid% pguidCmdGroup, 
    [InAttribute] unsigned int nCmdID, 
    [InAttribute] unsigned int nCmdexecopt, 
    [InAttribute] IntPtr pvaIn, 
    [InAttribute] IntPtr pvaOut
)
function ExecCommand(
    itemid : uint, 
    pguidCmdGroup : Guid, 
    nCmdID : uint, 
    nCmdexecopt : uint, 
    pvaIn : IntPtr, 
    pvaOut : IntPtr
) : int

Parameters

  • itemid
    Type: System.UInt32

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

  • pguidCmdGroup
    Type: System.Guid%

    [in, unique] Unique identifier of the command group; can be nulla null reference (Nothing in Visual Basic) to specify the standard group. All the commands that are passed in the nCmdID must belong to the group specified by pguidCmdGroup

  • nCmdID
    Type: System.UInt32

    [in] The command to be executed. This command must belong to the group specified with pguidCmdGroup.

  • nCmdexecopt
    Type: System.UInt32

    [in] Values describe how the object should execute the command.

    [1|1] nCmdexecopt value

    [1|2] Value

    [1|3] Description

    [2|1] OLECMDEXECOPT_DODEFAULT

    [2|2] 0

    [2|3] Prompt the user for input or not, depending on the default behavior

    [3|1] OLECMDEXECOPT_PROMPTUSER

    [3|2] 1

    [3|3] Execute the command after obtaining user input.

    [4|1] OLECMDEXECOPT_DONTPROMPTUSER

    [4|2] 2

    [4|3] Execute the command without prompting the user. For example, clicking the Print toolbar button causes a document to be immediately printed without user input.

    [5|1] OLECMDEXECOPT_SHOWHELP

    [5|2] 3

    [5|3] Show help for the corresponding command, but do not execute.

  • pvaIn
    Type: System.IntPtr

    [in, unique] Pointer to a VARIANTARG structure containing input arguments. Can be nulla null reference (Nothing in Visual Basic).

  • pvaOut
    Type: System.IntPtr

    [in, out, unique] VARIANTARG structure to receive command output. Can be nulla null reference (Nothing in Visual Basic).

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::ExecCommand(
   [in] VSITEMID itemid,
   [in, unique] const GUID * pguidCmdGroup,
   [in] DWORD nCmdID,
   [in] DWORD nCmdexecopt,
   [in, unique] VARIANT * pvaIn,
   [in, out, unique]VARIANT* pvaOut
);

This method is similar to the Exec method, except that the Exec method does not support hierarchies, whereas the IVsUIHierarchy.ExecCommand method includes the itemid parameter, which identifies the hierarchy item to which the command applies.

The environment executes IVsUIHierarchy.ExecCommand 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. These commands must not be handled through Exec. 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. To handle Delete and Remove for a project, use IVsHierarchyDeleteHandler.

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.

The command group VSConstants.VsUIHierarchyWindowCmdIds is used to handle direct UI manipulations in the UI hierarchy window.

VSHPROPID_EditLabel must be supported in GetProperty and SetProperty for item name editing to be enabled.

The following standard commands should only be handled using the IVsUIHierarchy interface:

// {5efc7975-14bc-11cf-9b2b-00aa00573819}

DEFINE_GUID(CLSID_StandardCommandSet97, 0x5efc7975, 0x14bc, 0x11cf, 0x9b, 0x2b, 0x00, 0xaa, 0x00, 0x57, 0x38, 0x19);

#define cmdidCopy 15

#define cmdidCut 16

#define cmdidDelete 17

#define cmdidPaste 26

#define cmdidRemove 168

#define cmdidRename 150

.NET Framework Security

See Also

Reference

IVsUIHierarchy Interface

IVsUIHierarchy Members

Microsoft.VisualStudio.Shell.Interop Namespace