Commands.AddNamedCommand Method (EnvDTE)

AddNamedCommand Method

Switch on low bandwidth view

Collapse All

Language Filter

This page is specific to

Microsoft Visual Studio 2005/.NET Framework 2.0

Other versions are also available for the following:

Visual Studio Automation and Extensibility Reference

Commands.AddNamedCommand Method

Creates a named command that is saved by the environment and made available the next time the environment starts, even if the Add-in is not loaded on environment startup.

Namespace: EnvDTE
Assembly: EnvDTE (in envdte.dll)

Syntax

Visual Basic (Declaration)

Function AddNamedCommand ( _
    <InAttribute> AddInInstance As AddIn, _
    <InAttribute> Name As String, _
    <InAttribute> ButtonText As String, _
    <InAttribute> Tooltip As String, _
    <InAttribute> MSOButton As Boolean, _
    <InAttribute> <OptionalAttribute> Optional Bitmap As Integer = 0, _
    <InAttribute> <OptionalAttribute> ByRef ContextUIGUIDs As Object(), _
    <InAttribute> <OptionalAttribute> Optional vsCommandDisabledFlagsValue As Integer = 16 _
) As Command

Visual Basic (Usage)

Dim instance As Commands
Dim AddInInstance As AddIn
Dim Name As String
Dim ButtonText As String
Dim Tooltip As String
Dim MSOButton As Boolean
Dim Bitmap As Integer
Dim ContextUIGUIDs As Object()
Dim vsCommandDisabledFlagsValue As Integer
Dim returnValue As Command

returnValue = instance.AddNamedCommand(AddInInstance, Name, ButtonText, Tooltip, MSOButton, Bitmap, ContextUIGUIDs, vsCommandDisabledFlagsValue)

Command AddNamedCommand (
    [InAttribute] AddIn AddInInstance,
    [InAttribute] string Name,
    [InAttribute] string ButtonText,
    [InAttribute] string Tooltip,
    [InAttribute] bool MSOButton,
    [OptionalAttribute] [InAttribute] int Bitmap,
    [OptionalAttribute] [InAttribute] ref Object[] ContextUIGUIDs,
    [OptionalAttribute] [InAttribute] int vsCommandDisabledFlagsValue
)

C++

Command^ AddNamedCommand (
    [InAttribute] AddIn^ AddInInstance, 
    [InAttribute] String^ Name, 
    [InAttribute] String^ ButtonText, 
    [InAttribute] String^ Tooltip, 
    [InAttribute] bool MSOButton, 
    [InAttribute] [OptionalAttribute] int Bitmap, 
    [InAttribute] [OptionalAttribute] array<Object^>^% ContextUIGUIDs, 
    [InAttribute] [OptionalAttribute] int vsCommandDisabledFlagsValue
)

Command AddNamedCommand (
    /** @attribute InAttribute() */ AddIn AddInInstance, 
    /** @attribute InAttribute() */ String Name, 
    /** @attribute InAttribute() */ String ButtonText, 
    /** @attribute InAttribute() */ String Tooltip, 
    /** @attribute InAttribute() */ boolean MSOButton, 
    /** @attribute InAttribute() */ /** @attribute OptionalAttribute() */ int Bitmap, 
    /** @attribute InAttribute() */ /** @attribute OptionalAttribute() */ /** @ref */ Object[] ContextUIGUIDs, 
    /** @attribute InAttribute() */ /** @attribute OptionalAttribute() */ int vsCommandDisabledFlagsValue
)

JScript

JScript does not support passing value-type arguments by reference.

Parameters

AddInInstance: Required. The AddIn Object is adding the new command.

Name: Required. The short form of the name for your new command. AddNamedCommand uses the preface, Addins.Progid., to create a unique name.

ButtonText: Required. The name to use if the command is bound to a button that is displayed by name rather than by icon.

Tooltip: Required. The text displayed when a user hovers the mouse pointer over any control bound to the new command.

MSOButton: Required. Indicates whether the named command's button picture is an Office picture. True = button. If MSOButton is False, then Bitmap is the ID of a 16x16 bitmap resource (but not an icon resource) in a Visual C++ resource DLL that must reside in a folder with the language's locale identifier (1033 for English).

Bitmap: Optional. The ID of a bitmap to display on the button.

ContextUIGUIDs: Optional. A SafeArray of GUIDs that determines which environment contexts (that is, debug mode, design mode, and so on) enable the command. See DisableFlags.

vsCommandDisabledFlagsValue: Optional. Determines whether the disabled state of the command is invisible or grey when you supply a ContextUIGUIDs and none are currently active.

Return Value

A Command object.

Remarks

Add-ins can later change the ButtonText name by responding to the QueryStatus method. If the text begins with "#", then the rest of the string is an integer that represents a resource ID in the Add-in's registered satellite DLL.

ppsaContextUIGUIDs is used when the Add-in is not loaded and thus cannot respond to the QueryStatus method. If ppsaContextUIGUIDs is empty, then the command is enabled until the Add-in is loaded and can respond to QueryStatus.

The Add-in can receive invocation notification through the IDTCommandTarget interface. A button can be added by using the OnConnection method of the IDTExtensibility2 interface

Example

Visual Basic

' Macro code.
Imports Microsoft.VisualStudio.CommandBars
Sub AddControlExample()
   ' Before running, you must add a reference to the Office 
   ' typelib to gain access to the CommandBar object. Also, for this 
   ' example to work correctly, there should be an add-in available 
   ' in the Visual Studio environment.
   Dim cmds As Commands
   Dim cmdobj As Command
   Dim cmdbarobj As CommandBar
   Dim colAddins As AddIns

   ' Set references.
   colAddins = DTE.AddIns()
   cmds = DTE.Commands
   cmdobj = cmds.Item("File.NewFile")

   ' Create a toolbar and add the File.NewFile command to it.
   cmds.AddCommandBar("Mycmdbar", _
   vsCommandBarType.vsCommandBarTypeToolbar)
   MsgBox("Commandbar name: " & cmdbarobj.Name)
   cmdobj.AddControl(cmdbarobj)
   cmds.AddNamedCommand(colAddins.Item(1), "MyCommand", _
   "Button Text", "Some tooltip", True)
End Sub

Reference

Commands Interface
Commands Members
EnvDTE Namespace