IApplication::AddCommand

  • Article

This method adds a command defined by an add-in.

HRESULT AddCommand(
  BSTR szCmdName,
  BSTR szMethodName,
  long nBitmapOffset,
  long dwCookie
  VARIANT_BOOL FAR* pbResult
);

Parameters

  • szCmdName
    [in]The collection of substrings that give the command identifiers, separated by a new line character ('\n'). The following table shows the substrings in proper order.

    Order Substring Description
    1 Name of the command The command you want to add.
    2 Text displayed on the toolbar button for the command The text that goes on a toolbar button.
    3 Status bar string The string displayed on the status bar or in the Customize dialog box when the user selects this command.
    4 Tooltip string The string displayed in the tool tip when the user holds the mouse pointer over the toolbar button assigned to the command.

    Note   Even if the add-in does not provide a toolbar button for a command, the add-in must provide all four substrings, because users can create toolbar buttons for commands added by add-ins.

  • szMethodName
    [in] The method exposed by the add-in to implement the command.

  • nBitmapOffset
    [in] The zero-based index into the medium and large command bar button bitmaps for this button image. For example, 0 (zero) represents the first image, 1 represents the second image, and so on. If the add-in does not provide a default image for toolbar buttons assigned to this command, the value of nBitmapOffset is -1.

  • dwCookie
    [in] The identifier of the add-in. The IDE passes this value to the add-in through the add-in IDSAddIn::OnConnection method.

  • pbResult
    [out] The pointer to a Boolean value. If the value is TRUE, then the command was added. If the value is FALSE, then the command was not added, because its name conflicted with the name of an existing command.

Return Values

None.

Remarks

Only add-ins can call the AddCommand method. VBScript macros cannot.

If the command name string supplied in szCmdName conflicts with an existing command, the IDE returns FALSE, keeps the existing command, and does not add this command. To prevent conflicts with existing commands, the add-in should prefix this command with the name of the add-in.

The following example shows the code automatically generated when you create an add-in using the Visual Studio Add-in Wizard:

VARIANT_BOOL bRet;
pApplication->AddCommand(bszCmdString, bszMethod, 0, m_dwCookie, &bRet);
if (bRet == VARIANT_FALSE)
{
   *OnConnection = VARIANT_FALSE;
   return S_OK;
}

Requirements

OS Versions: Windows CE .NET 4.1 and later.
Header: Appdefs.h.
Link Library: Import type library from Devshl.dll.

See Also

Macros and Add-ins | New Commands and Toolbar Buttons | IApplication::AddCommandBarButton | IApplication::EnableModeless | IApplication::SetAddInInfo

 Last updated on Friday, October 08, 2004

© 1992-2003 Microsoft Corporation. All rights reserved.