Implementing Commands with Interop Assemblies

  • [アーティクル]

VSPackages handle commands using the IOleCommandTarget or IVsUIHierarchy interfaces.

The IOleCommandTarget interface implements two methods:

  • The QueryStatus method queries an object for its command status and state.

  • The Exec method executes the command.

The IVsHierarchy interface implements two similar methods:

QueryStatus Method

The QueryStatus and QueryStatusCommand methods were written originally to support getting status on multiple commands by evaluating an array of command identifiers. If at all possible, you should continue to support multiple commands, that is, do not assume that only a single command is passed to your implementation of either of these two methods.

Among the parameters of the QueryStatus and QueryStatusCommand methods is the GUID of the command set to which the command belongs. Your implementation of either of these methods must check to see if it recognizes the GUID and can respond to the commands that are defined by that command set. Apply the following guidelines:

  • If the GUID is not recognized, your implementation of either method must return OLECMDERR_E_UNKNOWNGROUP.

  • If your implementation of either method recognizes the GUID but has not actually implemented the command, then the method should return OLECMDERR_E_NOTSUPPORTED.

  • If your implementation of either method recognizes both the GUID and the command, then the method should fill in the command flags field of each command (as contained in the array given by the prgCmds parameter) with the following, as it applies to that command:

    • If the command is supported:

      prgCmds[0].cmdf = OLECMDF_SUPPORTED;

    • If the command should not be visible at the moment:

      prgCmds[0].cmdf |= OLECMDF_INVISIBLE;

    • If the command is toggled on and appears to have been checked:

      prgCmds[0].cmdf |= OLECMDF_LATCHED;

    • If the command is enabled:

      prgCmds[0].cmdf |= OLECMDF_ENABLED;

    • If the command should be hidden if it appears on a context menu:

      prgCmds[0] cmdf |= OLECMDF_DEFHIDEONCTXMENU;

    • If the command is a menu controller and is not enabled but its drop-down menu list is not empty and is still available (this is a rarely used flag):

      prgCmds[0] cmdf |= OLECMDF_NINCHED;

  • If the command was defined in the Command Table Configuration (.Ctc) Files with the TextChanges flag, set the following parameters:

    • Set the rgwz element of the pCmdText parameter to the new text of the command.

    • Set the cwActual element of the pCmdText parameter to the size of the command string.

Exec Method

The Exec and ExecCommand methods are somewhat easier to implement than the QueryStatus or QueryStatusCommand methods. When the Exec or ExecCommand method of your VSPackage is called, confirm that your VSPackage recognizes both the GUID and the command. If the GUID or command is not recognized, follow the error return steps for the QueryStatus and QueryStatusCommand methods.

However, if your VSPackage recognizes the command, execute the command and return when you are done. Your VSPackage is responsible for error detection and notification, so if an error occurs while you are in the process of executing your command, report it. The environment assumes the VSPackage has handled the command if you return anything other than the error codes mentioned in the "QueryStatus Method" section.

For more information about the other parameters to the Exec method, such as the two VariantArgs and the nCmdexecopt, see the IOleCommandTarget interface. For more information about the parameters of the ExecCommand method, see the IVsUIHierarchy interface.

For example implementations of the QueryStatusCommand and ExecCommand methods, see the HierUtil7 sample library.

See Also

Concepts

How VSPackages Add User Interface Elements

Command Contracts Within Interop Assemblies

Command Routing in VSPackages

HierUtil7