Overview  Package   Class  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.esri.arcgis.framework
Interface ICommandBar

All Superinterfaces:
Serializable
All Known Implementing Classes:
CommandBar, ICommandBarProxy
public interface ICommandBar
extends Serializable

Provides access to members that modify a commandbar.

Remarks

Use the CommandBars collection on a Document object to get a reference to a command bar object.

Note, all programmatic customizations are temporary. If you execute VBA code to modify a commandbar or create a new menu, these changes are temporary. If you programmatically customize ArcMap, these changes will only appear while the current document is open in the current ArcMap session. Programmatic changes are never saved in the document or templates. Once you close that document or shutdown ArcMap, the changes are removed. If you are customizing ArcCatalog, these changes will only appear during the current ArcCatalog session.

The following example shows how to use the ICommandBars::Create method to create a new toolbar in Arcmap and add some items to it using the CommandBar::Add method. You would get m_app from the hook in ICommand::OnCreate().

When To Use

A CommandBar is a toolbar, menubar, menu, or context menu in the application. Use the ICommandBar interface to add commands, menus, or macro items to an existing command bar. Also use this interface to postion the command bar in the application.

Product Availability

Available with ArcGIS Desktop.

See Also:
ICommandBars.find(java.lang.Object, boolean, boolean)

Method Summary
 ICommandItem add(IUID cmdID, Object index)
          Adds a new command to this commandbar.
 ICommandItem createMacroItem(String name, Object faceID, String action, Object index)
          Creates a new macro item on this commandbar at the specified position.
 ICommandBar createMenu(String name, Object index)
          Creates a new blank menu on this commandbar at the specified position.
 void dock(int dockFlags, ICommandBar referenceBar)
          Docks or undocks this commandbar.
 ICommandItem find(Object identifier, boolean noRecurse)
          Finds a command on this commandbar.
 int getCount()
          The number of items contained within this commandbar.
 ICommandItem getItem(int index)
          The command item on this commandbar at the specified index.
 boolean isVisible()
          Indicates if this commandbar is visible.
 ICommandItem popup(int x, int y)
          Displays this commandbar as a popup menu at the specified location.
 

Method Detail

add

ICommandItem add(IUID cmdID,
                 Object index)
                 throws IOException,
                        AutomationException
Adds a new command to this commandbar.

Description

cmdID specifies the unique identifier of the command that is to be added to the commandbar.

Index specifies the postion on the commandbar at which this item is to be added. [Optional]

Remarks

In VBA, you can use the built-in ArcID module to find the unique identifier for a particular command or commandbar.

Product Availability

Available with ArcGIS Desktop.

Supported Platforms

Windows

Parameters:
cmdID - A reference to a com.esri.arcgis.system.IUID (in)
index - A Variant (in, optional, pass null if not required)
Returns:
A reference to a com.esri.arcgis.framework.ICommandItem
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
See Also:
IUID, ICommandItem

createMenu

ICommandBar createMenu(String name,
                       Object index)
                       throws IOException,
                              AutomationException
Creates a new blank menu on this commandbar at the specified position.

Description

Name is a string representing the caption of the menu. The caption is the string that appears for the menu when it is placed on a commandbar.

Index is a number representing the index location at which this menu is to appear on the commandbar. [Optional]

Remarks

If you want to create a new menu in a development environment other than VBA, you should implement IMenuDef instead of using ICommandBar::CreateMenu.

Product Availability

Available with ArcGIS Desktop.

Supported Platforms

Windows

Parameters:
name - The name (in)
index - A Variant (in, optional, pass null if not required)
Returns:
A reference to a com.esri.arcgis.framework.ICommandBar
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

createMacroItem

ICommandItem createMacroItem(String name,
                             Object faceID,
                             String action,
                             Object index)
                             throws IOException,
                                    AutomationException
Creates a new macro item on this commandbar at the specified position.

Description

Name is a string representing the caption of the macro item. The caption is the string that appears when the macro item is placed on a menu.

FaceID specifies the image to be used for the button when the macro item is on a toolbar. Use either an index number of an icon in the built-in icon palette or the picture property of an Image control on a UserForm. [Optional]

Action is a string representing the full name of the VBA macro that is to be executed when the macro item is clicked. The name of the macro must include the name of the VBA project in which this macro is located. [Optional]

Index is a number representing the index location at which this macro item is to appear on the commandbar. [Optional]

Remarks

The values for FaceID using the built-in icon palette are:

Here are some examples of the syntax of the Action parameter.

Macro called MyMacro in ThisDocument in Normal template:
"Normal.ThisDocument.MyMacro"

Macro called MyMacro in Module1 in Normal template:
"Normal.Module1.MyMacro"

Macro called MyMacro in ThisDocument in the current document:
"Project.ThisDocument.MyMacro"

Macro called MyMacro in Module1 in the current document:
"Project.Module1.MyMacro"

Macro called MyMacro in ThisDocument in a base template:
"TemplateProject.ThisDocument.MyMacro"

Macro called MyMacro in Module1 in a base template:
"TemplateProject.Module1.MyMacro"

Note: Macros must be Public Subs. Private Subs are not treated as macros.

Product Availability

Available with ArcGIS Desktop.

Supported Platforms

Windows

Parameters:
name - The name (in)
faceID - A Variant (in, optional, pass null if not required)
action - The action (in, optional, pass null if not required)
index - A Variant (in, optional, pass null if not required)
Returns:
A reference to a com.esri.arcgis.framework.ICommandItem
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
See Also:
ICommandItem

getCount

int getCount()
             throws IOException,
                    AutomationException
The number of items contained within this commandbar.

Product Availability

Available with ArcGIS Desktop.

Supported Platforms

Windows

Returns:
The count
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

find

ICommandItem find(Object identifier,
                  boolean noRecurse)
                  throws IOException,
                         AutomationException
Finds a command on this commandbar.

Description

identifier is the unique identifier of the item you want to find. For built-in commands and commandbars, use the UID. For VBA macros and UIControls use the name.

noRecurse Use False to do a recursive search for the item; otherwise use True. [Optional]

Remarks

Here is the syntax that can be used for identifier for each type of menu or command item that can be on the command bar.

Built-in commands and menus
Use the unique identifier (UID) of the command or menu. The built-in Normal.ArcID module can be used to find the UID's.


 pCommandBar.Find(ArcID.Edit_Menu)

 pCommandBar.Find(ArcID.File_AddData)

Instead of using the ArcID module, you can write your own code to get the UID of the object. 





To find the CLSID, ProgID, and subtype of an ESRI command or menu, refer to the following technical documents:

ArcObjects Developer Help > Technical Documents > ArcMap: Names and IDs of commands and commandbars

ArcObjects Developer Help > Technical Documents > ArcCatalog: Names and IDs of commands and commandbars 


Custom VBA menus 
Use a string that represents the full name of the custom menu. The name of the menu must include the project or template in which this menu was created. 



 pCommandBar.Find("Normal.New Menu")

 pCommandBar.Find("Project.New Menu")

 pCommandBar.Find("Project.New Menu 1")






When you create new menus using the Customize dialog, the first menu you create is named "New Menu", the second menu you create is called "New Menu 1", etc... In the Find method, you need to use the default name of the menu instead of the caption you assigned to it. Here is an example of how custom menu naming works.






If you write code to create a new menu, then the name of that item will be prefixed by the project or template in which the module was located.



UIControls 
Use a string that represents the full name of the UIControl. The name of the UIControl must include the project or template in which this UIControl was created. 



 pCommandBar.Find("Normal.UIButtonControl1")

 pCommandBar.Find("Project.UIToolControl1")

 pCommandBar.Find("TemplateProject.UICombboxControl1")






Macro Items 
Use a string that represents the full name of the VBA macro. The name of the macro must include the name of the VBA project and module in which this macro is located. Only Macros that are placed on a toolbar or menu can be found using CommandBars.Find. 



  pCommandBar.Find("Project.NewMacros.Test")

  pCommandBar.Find("Normal.ThisDocument.MyMacro")






Custom commands and menus
Use the unique identifier (UID) of your custom command or menu.
You can create a UID object and set the value of the UID to the CLSID or ProgID of your custom object.
For your custom objects, the ProgID is a string composed of the name of your project used to make the command and the class name of the command.
For example if you have a Visual Basic project called MyCustomTools and there is a class module for your command called cmdMyZoomTool in that project, then the ProgID for this command would be "MyCustomTools.cmdMyZoomTool".
To find the CLSID for this command, you could search the system registry for ProgID. Note, if you have a command that is a subtype then you also have to set the SubType property on IUID to the subtype value.

Product Availability

Available with ArcGIS Desktop.

Supported Platforms

Windows

Parameters:
identifier - A Variant (in)
noRecurse - The noRecurse (in, optional, pass false if not required)
Returns:
A reference to a com.esri.arcgis.framework.ICommandItem
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
See Also:
ICommandItem

getItem

ICommandItem getItem(int index)
                     throws IOException,
                            AutomationException
The command item on this commandbar at the specified index.

Product Availability

Available with ArcGIS Desktop.

Parameters:
index - The index (in)
Returns:
A reference to a com.esri.arcgis.framework.ICommandItem
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

popup

ICommandItem popup(int x,
                   int y)
                   throws IOException,
                          AutomationException
Displays this commandbar as a popup menu at the specified location.

Description

X is the X coordinate, in device units, of the point on the application where the commandbar should be displayed. Applies to menus and shortcut menus only. [Optional]

Y is the Y coordinate, in device units, of the point on the application where the commandbar should be displayed. Applies to menus and shortcut menus only. [Optional]

Product Availability

Available with ArcGIS Desktop.

Supported Platforms

Windows

Parameters:
x - The x (in, optional, pass 0 if not required)
y - The y (in, optional, pass 0 if not required)
Returns:
A reference to a com.esri.arcgis.framework.ICommandItem
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
See Also:
ICommandItem

dock

void dock(int dockFlags,
          ICommandBar referenceBar)
          throws IOException,
                 AutomationException
Docks or undocks this commandbar.

Description

dockFlags specifies whether the commandbar is docked or where it is docked. Use one of the esriDockFlags constants.

referenceBar is an ICommandBar object that is to be used as a location reference. [Optional]

Remarks

Use the esriDockFlags constants to specify whether this command bar is visible, floating, or where it is docked on the application.

Product Availability

Available with ArcGIS Desktop.

Supported Platforms

Windows

Parameters:
dockFlags - A com.esri.arcgis.framework.esriDockFlags constant (in)
referenceBar - A reference to a com.esri.arcgis.framework.ICommandBar (in, optional, pass null if not required)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
See Also:
esriDockFlags

isVisible

boolean isVisible()
                  throws IOException,
                         AutomationException
Indicates if this commandbar is visible.

Product Availability

Available with ArcGIS Desktop.

Supported Platforms

Windows

Returns:
The bVisible
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
Overview  Package   Class  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD